npm test: Usage, Options & Common CI Errors

Run your test suite - the exit code is the CI gate.

npm test (alias npm t) runs the test script from package.json. A non-zero exit code from the test runner fails the command, which fails the CI job.

What it does

Runs the "test" script, plus pretest and posttest hooks if defined. Unlike arbitrary scripts it needs no run keyword. The command succeeds only if the test process exits 0.

Common usage

Terminal

npm test                    # run the test script
npm t                       # short alias
npm test -- --coverage      # forward --coverage to the runner
npm test -- --runInBand     # serialize tests (lower memory in CI)

Common CI error: ELIFECYCLE / non-zero exit

CI fails with "npm error code ELIFECYCLE / Test failed. See above for more details" or exit code 1. npm is faithfully reporting that the test runner exited non-zero - the failure is in the tests or the runner, not npm. Scroll up to the actual assertion or crash; an exit 137 there means the runner was OOM-killed, not a test failure.

Terminal

# reduce memory pressure that causes SIGKILL/137 in CI:
npm test -- --runInBand --maxWorkers=2

Related guides

npm ELIFECYCLE / Exit Status Errors - Diagnose Failing npm ScriptsUnderstand npm ELIFECYCLE and non-zero "Exit status" errors in CI - they mean your script failed. How to find… npm "signal SIGKILL" / exit 137 in a Script - Fix Killed npm Step in CIFix npm "command failed signal SIGKILL" (exit 137) in CI - an npm script process killed by the OS, almost alw… Vitest / Jest Out of Memory (SIGKILL / exit 137) - Fix Test OOM in CIFix Vitest/Jest "JavaScript heap out of memory" or SIGKILL (exit 137) in CI - test runs that exhaust memory t…