Troubleshooting

command not found: semtest

Verify installation

Check if the package is installed globally:

npm list -g @westopp/semtest

If it's not listed, install it:

npm install -g @westopp/semtest

Verify PATH

Find the npm global bin directory:

npm prefix -g

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

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:

node --version

Upgrading Node.js

macOS (Homebrew):

brew upgrade node

nvm:

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:

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

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

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:

semtest init

Verify test discovery patterns

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

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.