Run a single test file with Jest

Select an exact test path, narrow test names with a regular expression, and troubleshoot configuration that still affects a focused run.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Best practices

Illustration of software testing and quality checks

Use --runTestsByPath when you want one exact test file:

npx jest --runTestsByPath tests/math.test.js

Run this from the intended project using its installed Jest version. A positional argument such as math.test.js is a path pattern and can match more than one file; it is not the same as selecting an exact path.

Choose a path or test name

npx jest math.test.js
npx jest tests/unit/
npx jest math
npx jest --runTestsByPath tests/math.test.js -t 'add function'

-t matches a regular expression against the full test name, including enclosing describe blocks. It does not select a JavaScript function by identifier. Escape regex metacharacters when they should be literal.

If your package's test script invokes Jest, pass additional arguments after --:

npm test -- --runTestsByPath tests/math.test.js

test.only(...) is another temporary way to focus a case, but it can suppress other tests in the same run. Remove it before sharing the change.

Use watch and diagnostic modes

npx jest --watch

In watch mode, press p for a file pattern or t for a test-name pattern. --watch normally focuses on changed tests and works with supported version-control integration; use --watchAll when you need all tests watched independently of that change filter.

For a focused diagnostic run:

npx jest --runTestsByPath tests/math.test.js --verbose
npx jest --runTestsByPath tests/math.test.js --coverage
npx jest --runTestsByPath tests/math.test.js --detectOpenHandles
npx jest --runTestsByPath tests/math.test.js --runInBand

Open-handle detection adds overhead and implies serial execution. Use it to investigate resources such as sockets and timers that keep the process alive.

If no tests are found

Check the selected configuration, root directory, ignored paths, and testMatch or testRegex. Even an exact path must belong to the selected Jest project's test set. In a monorepo, run from the correct package or explicitly select the intended configuration/project.

If a single file still starts expensive services

File selection does not bypass setupFiles, setupFilesAfterEnv, or applicable global setup. Identify which hook starts the service. Prefer an explicit lightweight test configuration or an on-demand fixture over silently removing setup needed by the tests. Coverage collection rules can also include files beyond the selected test.

For mocks, verify the module path relative to the test, the active moduleNameMapper, and the module system. ESM mocking has different requirements from CommonJS, so changing file selection alone will not repair it.

Reference: Jest CLI options.