semtest/Getting Started/Troubleshooting
Getting Started

Troubleshooting

Common issues and solutions when using semtest.

command not found: semtest

Verify installation

Check if the package is installed globally:

bash
npm list -g @westopp/semtest

If it's not listed, install it:

bash
npm install -g @westopp/semtest

Verify PATH

Find the npm global bin directory:

bash
npm prefix -g

Check if that directory's bin subdirectory is in your PATH:

bash
echo $PATH

Fix PATH

If the npm global bin directory is missing from your PATH, add it to your shell config. See the installation page for shell-specific instructions.

Homebrew users

Run brew doctor to check for PATH issues. Homebrew usually manages PATH automatically, but conflicts with other Node.js installations can cause problems.

Node.js version issues

semtest requires Node.js >= 20.

Check your version:

bash
node --version

Upgrading Node.js

macOS (Homebrew):

bash
brew upgrade node

nvm:

bash
nvm install 20
nvm use 20

Other platforms: download from nodejs.org.

Permission errors during global install

If you see EACCES errors when running npm install -g, do not use sudo. Instead, configure npm to use a directory you own:

bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Then add ~/.npm-global/bin to your PATH in your shell config:

bash
export PATH="~/.npm-global/bin:$PATH"

See npm's official guide on fixing permissions for more details.

semtest run can't find tests

Verify config exists

Make sure semtest.config.ts exists in your project root. If not, scaffold one:

bash
semtest init

Verify test discovery patterns

Open semtest.config.ts and check that testMatch includes patterns that match your spec files:

TS
export default defineConfig({
testMatch: ["**/*.spec.md", "**/*.test.md"],
// ...
});

Verify test files exist

Ensure your project contains at least one file matching the testMatch patterns. By default, semtest looks for *.spec.md and *.test.md files.

Previous← Quick startNextWriting tests →