skip to content

With npm, if package.json defines `pretest`, `test` and `posttest`, what does `npm test -- --coverage` run, and which script receives `--coverage`?

level: juniorimportance: should knowfreq 24%

answer

  1. names matched by prefix
  2. before, main, after
  3. a non-zero exit stops the chain
  4. the double dash ends npm's options
  5. arguments reach the main script only

basics

~20 s

npm runs pretest, then test with --coverage appended, then posttest, stopping at the first non-zero exit. Arguments after the double dash go only to the main test script, never to its pre or post hooks.

solid answer

~40 s

For any script `X`, npm runs `preX` before it and `postX` after it when they exist, so `npm test` runs `pretest`, `test`, `posttest`; the same works for invented names such as `prebuild` and `postbuild`. Everything after `--` is appended to the main script only — `test` becomes `vitest run --coverage`, while `pretest` and `posttest` get no extra arguments. Without the `--`, npm reads `--coverage` as one of its own options and the script never sees it. Each step must exit 0: a failing `pretest` means `test` never starts, and a failing `test` means `posttest` never runs. The main script must exist — a lone `pretest` with no `test` fails with `Missing script: "test"` unless `--if-present` is set — and `--ignore-scripts` still runs the named script but skips its hooks.

code

json · 8 lines
json
{
  "scripts": {
    "pretest": "npm run lint",
    "test": "vitest run",
    "posttest": "node scripts/report.js",
    "lint": "eslint src"
  }
}

go deeper

for a junior

Recall the order pre, main, post, that it works for any script name, and that flags for the tool go after a double dash so npm does not swallow them.

for a middle

Explain the edge rules: arguments reach only the main script, a non-zero exit stops the chain, a missing main script fails even with a pre hook, and --if-present changes that.

for a senior

Spot hooks that hide cost or break silently: a prebuild codegen skipped under ignore-scripts, a slow pretest, clean-up placed in a post hook that never runs after a failure.

for a principal

Treat hooks as implicit control flow: they are convenient but invisible in the command people type, so weigh them against an explicit script that names every step it runs.

## The convention npm treats the names in the `scripts` field as a small naming convention. For any script name `X`, a script called **`preX`** runs before it and one called **`postX`** runs after it, whenever they exist. The rule covers names you invent — `prebuild`, `postbundle` — and the built-in commands that run scripts: - `npm test` runs `pretest`, `test`, `posttest`; - `npm start` runs `prestart`, `start`, `poststart`; - `npm stop`, `npm restart` and `npm version` follow the same shape with their own names. `npm test` and `npm start` are shorthands for running those scripts; `npm run test` behaves the same way. ## The order npm follows For `npm test -- --coverage`, npm does this: 1. It looks up `test` in `scripts`. If there is no `test`, it stops with `Missing script: "test"` — **even when `pretest` exists** — unless `--if-present` is set, in which case it exits quietly with success. 2. If `pretest` exists, it runs first, with no extra arguments. 3. `test` runs with the extra arguments appended to its line. 4. If `posttest` exists, it runs last, with no extra arguments. Every step must exit with code 0. A non-zero exit aborts the sequence: a failing `pretest` means `test` never starts, and a failing `test` means `posttest` never runs. A `posttest` is therefore not a "finally" block; do not rely on it for clean-up after failures. ## A worked example Take a project whose `scripts` field reads: ```json { "pretest": "npm run lint", "test": "vitest run", "posttest": "node scripts/report.js", "lint": "eslint src" } ``` `npm test -- --coverage` then unfolds like this: `pretest` starts a nested `npm run lint`, which would itself honour a `prelint` or `postlint` if they existed; when `eslint src` exits 0, `test` runs as `vitest run --coverage`; only if the tests pass does `posttest` run `node scripts/report.js`, with no extra arguments. ## Where the arguments go The `--` tells npm's parser to stop reading its own options. Everything after it is passed to the script as **positional arguments**, appended to the script line, so `"test": "vitest run"` becomes `vitest run --coverage`. - Only the **main** script gets them. npm's source adds positional arguments to the main event only, never to `pre` or `post` hooks. - Without `--`, `npm test --coverage` makes npm treat `--coverage` as an npm option, so the script never receives it. - Positional arguments that do not start with a hyphen pass through even without `--`, but writing `--` every time is the habit that avoids surprises. If a hook needs the same setting, put it in the hook's own script line or have both scripts read an environment variable. ## What the scripts can see All three scripts run in the same prepared environment: - `node_modules/.bin` on `PATH`, so local tools run by name; - `npm_lifecycle_event` set to the stage being run (`pretest`, `test` or `posttest`), so one file can serve several hooks; - the package root as the working directory, with `INIT_CWD` holding the directory you started in. ## Settings that change the picture | Setting or call | Effect on the chain | |---|---| | `--if-present` | a missing main script exits 0 instead of failing | | `--ignore-scripts` | `npm test` and `npm run` still run the named script, but skip its `pre` and `post` hooks | | `npm run` with no name | lists the available scripts instead of running one | | a hook that calls `npm run lint` | `lint` runs with its own `prelint` and `postlint`, if defined | The `--ignore-scripts` row surprises people: a project that generates code in `prebuild` and has `ignore-scripts=true` in an `.npmrc` will run `build` without the generated files and fail with an unrelated-looking error. ## Common traps - **Hidden work.** A `pretest` that runs a full build makes every `npm test` slow, and newcomers do not see why, because `test` itself looks cheap. - **Lifecycle names are not ordinary hooks.** `prepare`, `prepublishOnly` and `prepack` are events npm itself fires during install, pack and publish, whether or not anyone runs a script by name. - **`npm run pack` is not `npm pack`.** The first runs a user script called `pack`; the second is npm's command that builds a tarball and fires `prepack` and `postpack`.

  • How can one script file behave differently when it is wired to several hooks?
    Read `npm_lifecycle_event`. npm sets it to the name of the stage being run — `pretest`, `test`, `posttest`, or a lifecycle event such as `prepare` — so a single file can branch on it instead of needing one file per hook.
  • Why is `posttest` a poor place for clean-up that must always happen?
    Because the chain stops at the first non-zero exit. If `test` fails, npm aborts and `posttest` never runs, so temporary servers or files it was meant to remove stay behind. Put must-run clean-up inside the test runner's own teardown instead.

  • Pre and post hooks work only for built-in names like test and start
  • Arguments after the double dash are passed to the pre and post hooks too
  • posttest always runs, even when the test script fails
  • A prebuild script on its own makes npm run build succeed
  • ignore-scripts stops npm test from running the test script itself