Skip to main content

Jest Runner

Installation​

Install @stryker-mutator/jest-runner locally within your project folder, like so:

npm i --save-dev @stryker-mutator/jest-runner
# OR
yarn add --dev @stryker-mutator/jest-runner

Peer dependencies​

The @stryker-mutator/jest-runner is a plugin for Stryker to enable Jest as a test runner. As such, you should make sure you have the correct versions of its dependencies installed:

  • jest
  • @stryker-mutator/core

For the minimum supported versions, see the peerDependencies section in the package.json.

Configuration​

Make sure you set the testRunner option to "jest".

{
  "testRunner": "jest"
}

The @stryker-mutator/jest-runner also provides a couple of configurable options using the jest property in your Stryker config:

{
  "jest": {
    "projectType": "custom",
    "configFile": "path/to/your/custom/jestConfig.js",
    "config": {
      "testEnvironment": "jest-environment-jsdom-sixteen"
    },
    "enableFindRelatedTests": true
  }
}

jest.projectType ["string"]​

Default: "custom"

Configure where jest should get its configuration from.

jest.configFile [string]​

Default: undefined

The path to your Jest config file of package.json file containing in the "jest" key. By default, the @stryker-mutator/jest-runner will try to look for "jest.conf.js" or "package.json" in the current working directory.

jest.config [object]​

Default: undefined

Custom Jest config. This will override file-based config.

jest.enableFindRelatedTests [boolean]​

Default: true

Whether to run jest with the --findRelatedTests flag. When true, Jest will only run tests related to the mutated file per test. (See --findRelatedTests).

ECMAScript Modules​

Jest ships with support for ECMAScript Modules (ESM). In order to provide the --experimental-vm-modules node option, you will need to add this to your stryker.config.json file:

{
  "testRunnerNodeArgs": ["--experimental-vm-modules"]
}

Coverage analysis​

The @stryker-mutator/jest-runner plugin supports coverage analysis and test filtering, meaning you can run with --coverageAnalysis perTest for optimal performance.

Coverage reporting​

When using "all" or "perTest" coverage analysis, this plugin reports mutant coverage by hooking into the jest's test environment. The test environment setting in your configuration file is overridden by default and you won't have to do anything here.

However, if you choose to override the jest-environment on a file-by-file basis using jest's @jest-environment docblock, you will have to do the work.

This:

/**
 * @jest-environment jsdom
 */

Becomes:

/**
 * @jest-environment @stryker-mutator/jest-runner/jest-env/jsdom
 */

This is the list of jest environments that are shipped with @stryker-mutator/jest-runner.

Jest test environment@stryker-mutator/jest-runner override
node@stryker-mutator/jest-runner/jest-env/node
jsdom@stryker-mutator/jest-runner/jest-env/jsdom
jest-environment-jsdom-sixteen@stryker-mutator/jest-runner/jest-env/jsdom-sixteen

Don't worry; using Stryker's alternative is harmless during regular unit testing.

If you're using a custom test environment, you'll need to mixin the Stryker functionality yourself:

// my-custom-jest-environment.js
const { mixinJestEnvironment } = require('@stryker-mutator/jest-runner');
const { TestEnvironment } = require('jest-environment-node');
// const TestEnvironment = require('jest-environment-node'); // 👈 Jest@27 or lower


class MyCustomTestEnvironment extends TestEnvironment {
  // custom magic here ✨
}

module.exports = mixinJestEnvironment(MyCustomTestEnvironment);

Test filtering​

When using "perTest" coverage analysis, the @stryker-mutator/jest-runner will hook into the jest test runner. Both "jasmine2" as well as jest-circus (default) are supported here.

If you're using a different test runner, you're out of luck. Please downgrade to using "all" coverage analysis. If you think we should support your test runner, please let us know by opening an issue, or by joining our slack channel.