npm-test

View documentation for the original command

$ tldr npm run

npm test [-- ]
npm t [-- ] (alias)

--
    Passes any subsequent arguments directly to the underlying test script. This is useful for passing options specific to the test runner being used (e.g., npm test -- --watch, npm test -- src/my-test.js).

--workspace , -w
    Runs the test script only in the specified workspace (a sub-package in a monorepo).

--workspaces, -ws
    Runs the test script in all configured workspaces within the project.

--if-present
    Prevents npm test from exiting with an error if the test script is not defined in package.json. The command will simply do nothing and exit successfully.

--silent, -s
    Suppresses npm's own output, showing only the output from the executed test script.

--loglevel
    Sets the verbosity level for npm's logging output (e.g., info, warn, error, debug).

The npm test command is a crucial part of the Node.js development workflow, providing a standardized way to execute tests for a project. It acts as an alias for npm run test, meaning it looks for a script named "test" within the scripts object of the project's package.json file. When found, it executes this script using the shell. This abstraction allows developers to define any test runner or command (e.g., jest, mocha, vitest, cypress run) as their test script, and other developers can simply use npm test without needing to know the specific underlying command. npm test runs within the project's root directory, with node_modules/.bin automatically added to the PATH, making executables installed via npm install directly available. It's typically used after installing dependencies (npm install) to ensure code quality and functionality. If no test script is explicitly defined, npm will usually indicate an error in newer versions, emphasizing the importance of defining this script for project health.

package.json Requirement: npm test requires a package.json file in the current directory or a parent directory to function correctly, as it relies on the scripts section.
Script Definition: The primary functionality of npm test depends on a test script being explicitly defined in package.json. While older npm versions might have attempted default test runners (like tap), modern npm typically errors if the script is missing, promoting best practices.
Lifecycle Hooks: npm test automatically runs pretest and posttest scripts if they are defined in package.json before and after the main test script execution, respectively. These can be used for setup or teardown tasks.

npm test is merely a convenience alias for npm run test. It looks for a script named test in the scripts object of the package.json file. The command specified in this test script is then executed in a shell, with the node_modules/.bin directory automatically added to the shell's PATH. This means any executables installed as part of your project's dependencies (e.g., jest, mocha, vitest) are directly runnable without needing their full path.

In earlier versions of npm (e.g., pre-npm v7), if a test script was not explicitly defined in package.json, npm test might attempt to run a default command like node_modules/.bin/tap --bail. However, in modern npm versions (v7 and later), the default behavior if the test script is missing is generally to exit with an error, unless the --if-present flag is used. It is considered best practice to always explicitly define your test script.

The npm test command has been a foundational part of the npm CLI since its early days, establishing a consistent and universal method for running project tests in the Node.js ecosystem. Its role as an alias for npm run test simplifies test execution, allowing developers to define complex testing workflows in their package.json while providing a simple, memorable interface. Over time, while the core functionality has remained constant, the default behavior for when no test script is defined has evolved, shifting from attempting to run a default test runner (like tap) to more explicitly requiring the script to be defined, aligning with a stronger emphasis on explicit configuration.

npm(1), npm run-script(1), npm install(1), package.json(5)