With npm, if package.json defines `pretest`, `test` and `posttest`, what does `npm test -- --coverage` run, and which script receives `--coverage`?
answer
- names matched by prefix
- before, main, after
- a non-zero exit stops the chain
- the double dash ends npm's options
- arguments reach the main script only
basics
~20 snpm 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 sFor 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{
"scripts": {
"pretest": "npm run lint",
"test": "vitest run",
"posttest": "node scripts/report.js",
"lint": "eslint src"
}
}go deeper
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.
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.
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.
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