Troubleshooting

In this tutorial, you will learn the steps to take when something goes wrong. This will be your guide to resolving issues with Jest.

Tests are Failing and You Don't Know Why

When you find out that your tests are failing and you can't pinpoint what caused them. You should try using the debugging built into Node (this only works for Node.js 8+).

You need to place a debugger; statement in any of your tests, and then, run the snippet shown below in your project's directory:

node --inspect-brk node_modules/.bin/jest --runInBand [any other arguments here]

or on Windows

node --inspect-brk ./node_modules/jest/bin/jest.js --runInBand [any other arguments here]

This runs Jest in a Node process that an external debugger can connect to. Note that the process pauses until the debugger has connected to it.

If you want to debug in Google Chrome (or any Chromium-based browser), all you need to do is to open your browser and go to chrome://inspect and click on the "Open Dedicated DevTools for Node", this gives you a list of available node instances you can connect to. Simply click on the address that is displayed in the terminal (usually this will be something like localhost:9229) after running the above command, and you can then debug Jest using Chrome's DevTools.

The Chrome Developer Tools will then be displayed, and a breakpoint set at the first line of the Jest CLI script (this is done just to give you time to open the developer tools and to prevent Jest from executing before you have time to do so). You should click the button that looks like a "play" button in the upper right hand side of the screen to continue execution. When the test that contains the debugger statement is executed by Jest, execution pauses and you can then examine the current scope and call stack.

Note: the --runInBand cli option will make sure Jest runs test in the same process rather than spawning processes for individual tests. Normally Jest will parallelize test runs across processes but it is always hard to debug many processes at the same time.

Debugging in VS Code

You can debug Jest tests with Visual Studio Code's built in debugger in multiple ways.

For you to attach the built-in debugger, you need to run your tests as we mentioned in the previous section:

node --inspect-brk node_modules/.bin/jest --runInBand [any other arguments here]

or on Windows

node --inspect-brk ./node_modules/jest/bin/jest.js --runInBand [any other arguments here]

The next step is to attach VS Code's debugger using the launch.json config:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach",
      "port": 9229
    }
  ]
}

If you want to automatically launch and attach to a process running your tests, you should use the configuration shown below:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "runtimeArgs": [
        "--inspect-brk",
        "${workspaceRoot}/node_modules/.bin/jest",
        "--runInBand"
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "port": 9229
    }
  ]
}

Use the following configuration for windows:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "runtimeArgs": [
        "--inspect-brk",
        "${workspaceRoot}/node_modules/jest/bin/jest.js",
        "--runInBand"
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "port": 9229
    }
  ]
}

In the case where you are using the create-react-app from Facebook, you can debug your Jest tests with this configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug CRA Tests",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/react-scripts",
      "args": ["test", "--runInBand", "--no-cache", "--env=jsdom"],
      "cwd": "${workspaceRoot}",
      "protocol": "inspector",
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

Debugging in WebStorm

Using Jest run/debug configuration is the easiest way to debug Jest tests in WebStorm. It launches tests and automatically attach debugger.

In the WebStorm menu Run you should select Edit Configurations.... Then click + and select Jest. Then you have to optionally specify the Jest configuration file, additional options, and environment variables. Save this configuration, and put breakpoints in the code, finally click the green debug icon to start debugging.

In the case where you are using Facebook's create-react-app, in the Jest run/debug configuration, you should specify the path to the react-scripts package in the Jest package field and then add --env=jsdom to the Jest options field.

Caching Issues

If you encounter caching issues you should know that the transform script was changed or that Babel was updated and the changes are not being recognized by Jest?

The solution is to retry with --no-cache. Jest will cache transformed module files to speed up test execution. In the case where you are using your own custom transformer, you should consider adding a getCacheKey function to it.

Unresolved Promises

What if a promise doesn't resolve at all? you might get this error:

- Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.

Most often this is being caused by conflicting Promise implementations. You should consider replacing the global promise implementation with your own, for instance global.Promise = jest.requireActual('promise'); and/or you consolidate the used Promise libraries to a single one.

In the case where your test is long running, you may want to consider increasing the timeout by calling jest.setTimeout

jest.setTimeout(10000); // 10 second timeout

Watchman Issues

The solution to watchman issues is to try running Jest with --no-watchman or setting the watchman configuration option to false.

Tests are Extremely Slow on Docker and/or Continuous Integration (CI) server.

While Jest is most of the time extremely fast on modern multi-core computers that has fast SSDs, users have discovered it to be slow on certain setups.

One way to mitigate this issue and improve Jest's speed by up to 50% is to run tests sequentially.

In order to do this, you can run tests in the same thread using --runInBand:

# Using Jest CLI

jest -runInBand

# Using yarn test (e.g. with create-react-app)

yarn test -runInBand

An alternative to expediting test execution time on Continuous Integration Servers such as Travis-CI is to set the max worker pool to ~4. On Travis-CI, this can help you to reduce test execution time by half. Note: The Travis CI free plan that is available for open source projects only includes 2 CPU cores.

# Using Jest CLI

jest --maxWorkers=4

# Using yarn test (e.g. with create-react-app)

yarn test --maxWorkers=4

Compatibility issues

Jest will take advantage of new features added to Node 6. Just as we recommend, please upgrade to the latest stable release of Node. Version v6.0.0 is the minimum supported version. Versions 0.x.x and 4.x.x are not supported because the jsdom version used in Jest does not support Node 4. However, if you have to run Jest on Node 4, you may use the testEnvironment config to use a custom environment that supports Node 4, for example jest-environment-node.

coveragePathIgnorePatterns seems to not have any effect.

You should ensure that you are not using the babel-plugin-istanbul plugin. Jest will wrap Istanbul, and will also tell Istanbul what files to instrument with coverage collection. When you are using babel-plugin-istanbul, every file that is processed by Babel have coverage collection code, hence it will not be ignored by coveragePathIgnorePatterns.

Defining Tests

Tests have to be defined synchronously for Jest to be able to collect your tests.

For instance to show why this is the case, imagine that we wrote a test like so:

// Don't do this it will not work

setTimeout(() => {
  it('passes', () => expect(1).toBe(1));
}, 0);

When Jest runs your test to collect the test s, it won't find any, this is because we have set the definition to happen asynchronously on the next tick of the event loop.

Note: This means that when you are using test.each , you cannot set the table asynchronously within a beforeEach / beforeAll.

Previous: Testing React Apps
Next: testing-web-frameworks