Jest Runner

Installation#

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

npm i --save-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.

"custom": use the jest.config custom configuration.
"create-react-app": use react-scripts, for projects created with create-react-app.
"create-react-app-ts": DEPRECATED use react-scripts-ts, for projects created with create-react-app-typescript. DEPRECATED, please follow the migration guide and move to create-react-app.

`jest.configFile`] [`string`]#

Default: undefined

The path to your Jest config file.

`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).

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 is overridden based on the "testEnvironment" configuration option in your jest config:

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

As long as you're using one of these test environments, you won't have to do anything.

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/jsom 
 */

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 NodeEnvironment = require('jest-environment-node');

class MyCustomTestEnvironment extends NodeEnvironment {
  // 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 the default "jasmine2" as well as jest-circus 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.