Rush StackShopBlogEvents

Jest plugin

Plugin package:@rushstack/heft-jest-plugin
Plugin name:jest-plugin implemented by JestPlugin.ts
Plugin config file:Jest's jest.config.json loaded by @rushstack/heft-config-file for rigging
heft.json options:IJestPluginOptions

This plugin invokes the Jest test framework for unit testing.

When to use it

We recommend Jest for several reasons:

  • All-in-one: Unlike frameworks such as mocha that require many components to be hooked together, Jest provides a single integrated solution for your: test runner, assertion library, mock/spy API, instrumentation, code coverage, and reporting. Jest also has first class support for React.

  • Interactive: Jest supports a "watch mode" for automatically re-running tests whenever a file is saved, plus a snapshot testing that can automatically update assertions when a contract changes.

  • Isolated runtime: Jest runs web tests in a Node.js environment rather than launching a web browser, and leverages the Node.js VM feature to prevent tests from leaking state.

That said, if for some reason you need to run tests in some other runtime such as an Android client or real web browser, Jest may not be the best bet.

package.json dependencies

If you are using a standard rig such as @rushstack/heft-node-rig or @rushstack/heft-web-rig, then Jest will already be loaded and configured.

Otherwise, you'll need to add the plugin package to your project:

# If you are using Rush, run this shell command in your project folder:
rush add --package @rushstack/heft-jest-plugin --dev

The plugin has direct dependencies on the Jest packages that it needs, so you don't need to add Jest to your project's package.json file.

Your project should get its typings from @types/heft-jest instead of @types/jest:

# If you are using Rush, run this shell command in your project folder:
rush add --package @types/heft-jest --dev --exact

# Because @types packages don't follow SemVer, it's a good idea to use --exact

...and then reference the @types/heft-jest in your tsconfig.json file, like this example:

"extends": "./node_modules/@rushstack/heft-node-rig/profiles/default/tsconfig-base.json",
"compilerOptions": {
"types": [
"heft-jest", // <---- ADD THIS


If Jest is not already being provided by a rig, your heft.json config file could invoke it like in this example:

<project folder>/config/heft.json

"$schema": "",

"phasesByName": {
"build": {
. . .
"test": {
"phaseDependencies": ["build"],
"tasksByName": {
"jest": {
"taskPlugin": {
"pluginPackage": "@rushstack/heft-jest-plugin"

Heft looks for Jest's config file in the standard path config/jest.config.json. Although Jest itself supports other config file names and even embedding settings in your package.json file, Heft requires the name config/jest.config.json. In a large scale monorepo, enforcing one standard filename makes it easier to search for these files, perform bulk edits, and copy configuration recipes between projects.

For a simple setup, your Jest configuration should extend Heft's jest-shared.config.json like this:

<project folder>/config/jest.config.json

"extends": "@rushstack/heft-jest-plugin/includes/jest-shared.config.json"

Alternatively, if you are using a rig package such as @rushstack/heft-web-rig, specify the rig like in this example:

<project folder>/config/jest.config.json

"extends": "@rushstack/heft-web-rig/profiles/library/config/jest.config.json"

(If you maintain your own rig, it should extend from @rushstack/heft-jest-plugin to ensure that Jest uses Heft's transforms and resolver.)

Note: If you find yourself frequently adding lots of custom settings to jest.config.json, please create a GitHub issue and tell us about it. Our aim is to provide a configuration that minimizes the need for project-specific customizations.

The "extends" field

The "extends" field in jest.config.json is a Heft-specific enhancement that will not work if the Jest command line is invoked without Heft. This setting replaces Jest's "preset" field which has limited module resolution capabilities and does not support rigs. Heft parses jest.config.json using the @rushstack/heft-config-file engine, with full support for property inheritance directives.

If for some reason your jest.config.json needs to be directly readable by Jest, the disableConfigurationModuleResolution plugin setting can be used to restore the standard behavior, with the downside that your Jest configuration will not be riggable.

For example:

<project folder>/config/heft.json

"$schema": "",

"phasesByName": {
"build": {
. . .
"test": {
"phaseDependencies": ["build"],
"tasksByName": {
"jest": {
"taskPlugin": {
"pluginPackage": "@rushstack/heft-jest-plugin",
"options": {
// (Not recommended) Disable Heft's support for rigs and the "extends" field
"disableConfigurationModuleResolution": true

Differences from ts-jest

Conventionally, Jest supports TypeScript compilation via plugins called transforms, which are modeled as a function that receives a single .ts file as input, and returns a .js file and .map file as its output. The official babel-jest transform actually does compile one file at a time, but that approach cannot support language features such as const enum that require analyzing imported types. The popular ts-jest transform solves that problem by performing a full compiler analysis and reusing it each time the transform is invoked, but this won't support other build steps such as preprocessors. Both babel-jest and ts-jest also impose a significant performance cost, by invoking the compiler a second time when running tests.

Heft takes a different approach of performing a conventional build and then invoking Jest on the output. If your build targets a browser runtime, you'll need to use the additionalModuleKindsToEmit setting to emit CommonJS outputs in a secondary folder. (Emitting extra files is still significantly faster than invoking the compiler twice.) Besides avoiding redundant compiler invocations, Heft's strategy ensures that your unit tests are compiled with your full build process including any preprocessor tasks such as Sass typings generation.

Some helpful examples of mocking and other Jest techniques can be found in the heft-node-jest-tutorial project folder.

Important differences when using Jest with Heft:

  • Invoke Jest using the heft command line. Invoking the jest command line directly will not invoke TypeScript and is incompatible with the "extends" field from jest.config.json.

  • Do not add ts-jest or babel-jest as a dependency for your project.

  • Instead of import { mocked } from "ts-jest/utils";, use the global mocked() function that is provided by @types/heft-jest. Besides this difference, the API documentation from ts-jest is still applicable to Heft's implementation.

  • The ts-jest transform will magically "hoist" calls to jest.mock();. Heft does not consider this a best practice. Instead, use the @rushstack/hoist-jest-mock lint rule to remind developers to manually hoist their calls. It is enabled by default with @rushstack/eslint-config.

Debugging Jest tests

To debug your Jest tests, it's recommended create a VS Code launch.json file like this:

<project folder>/.vscode/launch.json

"version": "0.2.0",
"configurations": [
"type": "node",
"request": "launch",
"name": "Debug Jest tests",
"program": "${workspaceFolder}/node_modules/@rushstack/heft/lib/start.js",
"cwd": "${workspaceFolder}",
"args": ["--debug", "test", "--clean"],
"console": "integratedTerminal",
"sourceMaps": true

This launches the full Heft toolchain in your debugger. The --debug switch prevents Jest from being spawned as a separate process. The --clean flag is optional, but fixes an issue where in rare situations Jest's "haste-map" may become corrupted by an aborted run.

To restrict the debugger to run one specific test, you can add the --test-name-pattern parameter. (See here for command-line documentation.) Another option is to use Jest's test.only() API.

CLI parameters

heft-jest-plugin/heft-plugin.json defines these parameters:

  --config RELATIVE_PATH
Use this parameter to control which Jest
configuration file will be used to run Jest tests. If
not specified, it will default to "config/jest.config.
json". This corresponds to the "--config" parameter
in Jest's documentation.
Normally Heft installs a custom Jest reporter so that
test results are presented consistently with other
task logging. If you suspect a problem with the
HeftJestReporter, specify "--debug-heft-reporter" to
temporarily disable it so that you can compare with
how Jest's default reporter would have presented it.
Include this output in your bug report. Do not use
"--debug-heft-reporter" in production.
Attempt to collect and print open handles preventing
Jest from exiting cleanly. This option has a
significant performance penalty and should only be
used for debugging. This corresponds to the
"--detectOpenHandles" parameter in Jest's
Disable any configured code coverage. If code
coverage is not configured, this parameter has no
--find-related-tests SOURCE_FILE
Find and run the tests that cover a source file that
was passed in as an argument. This corresponds to the
"--findRelatedTests" parameter in Jest's
documentation. This parameter is not compatible with
watch mode.
Use this parameter to control maximum number of
worker processes tests are allowed to use. This
parameter is similar to the parameter noted in the
Jest documentation, and can either be an integer
representing the number of workers to spawn when
running tests, or can be a string representing a
percentage of the available CPUs on the machine to
utilize. Example values: "3", "25%"
Prevent tests from printing messages through the
console. This corresponds to the "--silent" parameter
in Jest's documentation.
-t REGEXP, --test-name-pattern REGEXP
Run only tests with a name that matches a regular
expression. The REGEXP is matched against the full
name, which is a combination of the test name and all
its surrounding describe blocks. This corresponds to
the "--testNamePattern" parameter in Jest's
--test-path-ignore-patterns REGEXP
Avoid running tests with a source file path that
matches one ore more regular expressions. On Windows
you will need to use "/" instead of "\". This
corresponds to the "--testPathIgnorePatterns"
parameter in Jest's documentation.
--test-path-pattern REGEXP
Run only tests with a source file path that matches a
regular expression. On Windows you will need to use
"/" instead of "\". This corresponds to the
"--testPathPattern" parameter in Jest's documentation.
--test-timeout-ms TIMEOUT
Change the default timeout for tests; if a test
doesn't complete within this many milliseconds, it
will fail. Individual tests can override the default.
If unspecified, the default is normally 5000 ms. This
corresponds to the "--testTimeout" parameter in
Jest's documentation.
-u, --update-snapshots
Update Jest snapshots while running the tests. This
corresponds to the "--updateSnapshots" parameter in

heft.json plugin options

When loading @rushstack/heft-jest-plugin in your heft.json, the following settings can be provided inline using the "options" field:


export interface IJestPluginOptions {
configurationPath?: string;
debugHeftReporter?: boolean;
detectOpenHandles?: boolean;
disableCodeCoverage?: boolean;
disableConfigurationModuleResolution?: boolean;
findRelatedTests?: string[];
maxWorkers?: string;
passWithNoTests?: boolean;
silent?: boolean;
testNamePattern?: string;
testPathIgnorePatterns?: string;
testPathPattern?: string;
testTimeout?: number;
updateSnapshots?: boolean;

Their function is identical to the corresponding command-line parameters.

See also