@nx/jest

Jest is an open source test runner created by Facebook. It has a lot of great features:

  • Immersive watch mode for providing near instant feedback when developing tests.
  • Snapshot testing for validating features.
  • Great built-in reporter for printing out test results.

Setting up Jest

By default, Nx will use Jest when creating applications and libraries.

Adding Jest to an Existing Project

Add Jest to a project using the jest-project generator from @nx/jest.

First, install @nx/jest, if not already installed using your preferred package manager.

npm install --save-dev @nx/jest
Nx 15 and lower use @nrwl/ instead of @nx/

Once installed, run the jest-project generator

nx g @nx/jest:jest-project --project=<project-name>
Nx 15 and lower use @nrwl/ instead of @nx/

Hint: You can use the --dry-run flag to see what will be generated.

Replacing <project-name> with the name of the project you're wanting to add Jest too.

Using Jest

Testing Applications

The recommended way to run/debug Jest tests via an editor

To run Jest tests via nx use

nx test frontend

Watching for Changes

Using the --watch flag will run the tests whenever a file changes.

nx test frontend --watch

Snapshot Testing

Jest has support for Snapshot Testing, a tool which simplifies validating data. Check out the official Jest Documentation on Snapshot Testing.

Example of using snapshots:

describe('SuperAwesomFunction', () => { it('should return the correct data shape', () => { const actual = superAwesomFunction(); expect(actual).toMatchSnapshot(); }); });

When using snapshots, you can update them with the --updateSnapshot flag, -u for short.

By default, snapshots will be generated when there are not existing snapshots for the associated test.

nx test frontend -u

Snapshot files should be checked in with your code.

Performance in CI

Typically, in CI it's recommended to use nx affected -t test --parallel=[# CPUs] -- --runInBand for the best performance.

This is because each jest process creates a workers based on system resources, running multiple projects via nx and using jest workers will create too many process overall causing the system to run slower than desired. Using the --runInBand flag tells jest to run in a single process.

Configurations

Jest

Primary configurations for Jest will be via the jest.config.ts file that generated for your project. This file will extend the root jest.preset.js file. Learn more about Jest configurations.

The root level jest.config.ts file configures Jest multi project support. This configuration allows editor/IDE integrations to pick up individual project's configurations rather than the one at the root.

The set of Jest projects within Nx workspaces tends to change. Instead of statically defining a list in jest.config.ts, Nx provides a utility function called getJestProjects which queries for Jest configurations defined for targets which use the @nx/jest:jest executor.

You can add Jest projects which are not included in getJestProjects(), because they do not use the Nx Jest executor, by doing something like the following:

import { getJestProjects } from '@nx/jest'; export default { projects: [...getJestProjects(), '<rootDir>/path/to/jest.config.ts'], };
Nx 15 and lower use @nrwl/ instead of @nx/

Nx

Nx Jest Plugin options can be configured via the project config file or via the command line flags.

Hint: Use --help to see all available options

nx test <project-name> --help

Code Coverage

Enable code coverage with the --coverage flag or by adding it to the executor options in the project configuration file.

By default, coverage reports will be generated in the coverage/ directory under projects name. i.e. coverage/apps/frontend. Modify this directory with the --coverageDirectory flag. Coverage reporters can also be customized with the --coverageReporters flag.

coverageDirectory and coverageReporters are configurable via the project configuration file as well.

Global setup/teardown with nx libraries

In order to use Jest's global setup/teardown functions that reference nx libraries, you'll need to register the TS path for jest to resolve the libraries. Nx provides a helper function that you can import within your setup/teardown file.

global-setup.ts
import { registerTsProject } from '@nx/js/src/internal'; const cleanupRegisteredPaths = registerTsProject('.', 'tsconfig.base.json'); import { yourFancyFunction } from '@some-org/my-util-library'; export default async function () { yourFancyFunction(); } // make sure to run the clean up! cleanupRegisteredPaths();
Nx 15 and lower use @nrwl/ instead of @nx/
@swc/jest & global scripts

When using @swc/jest and a global setup/teardown file, You'll have to set the global setup/teardown file to be transformed with ts-jest. For example, if your files are named global-setup.ts and global-teardown.ts, then you would need to add to your project level jest.config.ts a new entry in the transformers object

apps/<your-project>/jest.config.ts
export default { transform: { 'global-(setup|teardown).ts': 'ts-jest', // resest of the transformers }, };

More Documentation

Package reference

Here is a list of all the executors and generators available from this package.

Guides

Executors

  • jest

    Run Jest unit tests.

Generators

  • initInternal

    Initialize the @nrwl/jest plugin.

  • jest-projectInternal

    Add Jest configuration to a project.