Skip to main content

Configuration

This page describes the available configuration options in Stryker's core package. Please keep in mind that your plugins might also need configuration, see your plugin's configuration page for that.

All configuration options can either be set via the command line or via a config file.

The ignorePatterns and mutate options (and some others) support globbing expressions using node glob. See the config file documentation for more information.

allowConsoleColors [boolean]

Default: true
Command line: --allowConsoleColors true
Config file: "allowConsoleColors": true

The allowConsoleColors value indicates whether Stryker should use colors in console.

buildCommand [string]

Default: undefined
Command line: [-b|--buildCommand] "npm run build"
Config file: "buildCommand": 'npm run build'

Configure a build command to run after mutating the code, but before mutants are tested. This is generally used to transpile your code before testing. Only configure this if your test runner doesn't take care of this already and you're not using just-in-time transpiler like babel/register or ts-node.

checkers [string[]]

Default: []
Command line: --checkers typescript
Config file: "checkers": ["typescript"]

Enable checker plugins here. A checker plugin will be invoked for each mutant before it is run in a test runner. It can check to see of a given mutant is valid, by for example validate that it won't result in a type error.

See typescript-checker for an example of a checker plugin.

checkerNodeArgs [string[]]

Default: []
Command line: --checkerNodeArgs "--inspect-brk --cpu-prof"
Config file: "checkerNodeArgs": ["--inspect-brk", "--cpu-prof"]

Configure arguments to be passed as exec arguments to the checker child process. For example, running Stryker with --concurrency 1 --checkerNodeArgs "--inspect-brk" will allow you to debug the checker child process. See execArgv of child_process.fork.

cleanTempDir [boolean]

Default: true
Command line: --cleanTempDir false
Config file: "cleanTempDir": false

Choose whether or not to clean the temp dir (which is ".stryker-tmp" inside the current working directory by default) after a successful run. The temp dir will never be removed when the run failed for some reason (for debugging purposes).

clearTextReporter [ClearTextOptions]

Default: { "allowColor": true, "allowEmojis": false, "logTests": true, "maxTestsToLog": 3 }

Config file:

{
"clearTextReporter": {
"allowColor": true,
"allowEmojis": false,
"logTests": true,
"maxTestsToLog": 3
}
}

Settings for the clear-text reporter.

concurrency [number]

Default: cpuCoreCount <= 4? cpuCoreCount : cpuCoreCount - 1
Command line: --concurrency 4
Config file: "concurrency": 4

Set the concurrency of workers. This defaults to n-1 where n is the number of logical CPU cores available on your machine, unless n <= 4, in that case it uses n. This is a sane default for most use cases.

commandRunner [object]

Default: { command: 'npm test' }
Command line: none
Config file: "commandRunner": { "command": "npm run mocha" }

With commandRunner, you can specify the command to execute for running tests.

coverageAnalysis [string]

Default: perTest
Command line: --coverageAnalysis perTest
Config file: "coverageAnalysis": "perTest"

Note: The default changed from "off" to "perTest" in Stryker v5.

With coverageAnalysis you specify which coverage analysis strategy you want to use.

Stryker can analyze mutant coverage results. Doing this can speed up mutation testing because Stryker then decides to run only the exact tests covering the mutant it is testing (instead of running them all). This performance optimization does not influence the resulting mutation testing score but does allow Stryker to distinguish between "Survived" and "NoCoverage".

All official test runner plugins (@stryker-mutator/mocha-runner, @stryker-mutator/jasmine-runner, @stryker-mutator/karma-runner and @stryker-mutator/jest-runner) support coverage analysis, except for the command test runner, since Stryker will just run your command has no way of knowing more about your tests.

The possible values are:

  • off: Stryker does no optimization. All tests are executed for each mutant.
  • all: Stryker will determine the mutants covered by your tests during the initial test run phase. Mutants without code coverage will be reported with NoCoverage and will not be tested. This requires your test runner plugin to report code coverage back to Stryker.
  • perTest: Stryker will determine which tests cover which mutant during the initial test run phase. Only the tests that cover a specific mutant are executed for each mutant. Your tests should be able to run independently of each other and in random order. Stryker will determine which mutants are static and will run all tests for them during mutation testing. A mutant is 'static' when it is executed during the loading of the file rather than during a test.

dashboard [DashboardOptions]

Default: { baseUrl: 'https://dashboard.stryker-mutator.io/api/reports', reportType: 'mutationScore' }
Command line:

  • --dashboard.project github.com/my-org/my-project --dashboard.version branch-or-tag
  • --dashboard.module my-module
  • --dashboard.baseUrl https://dashboard.stryker-mutator.io/api/reports
  • --dashboard.reportType full

Config file:

{
"dashboard": {
"project": "github.com/my-org/my-project",
"version": "branch-or-tag",
"module": "my-module",
"baseUrl": "https://dashboard.stryker-mutator.io/api/reports",
"reportType": "full"
}
}

Settings for the dashboard reporter. See the dashboard documentation for more info.

disableBail [boolean]

Since v5.4

Default: false
Command: --disableBail
Config file: "disableBail": true

Configure the test runner to report all failing tests when a mutant is killed instead of bailing after the first failing test. Bailing brings better performance, but you might be interested in the full report instead. This might be useful when using the "Tests" view to hunt for tests that don't kill a single mutant.

See the difference of bail vs no bail on StrykerJS's utils package (with --concurrency 4):

With bail (in 2m 33s)Disable bail (in 2 m 45s)
with bailDisable bail

As you can see, when you disable bail, a lot more tests get the "Killing" status, meaning that they killed at least 1 mutant. This does come with a performance penalty of 12s in this example.

Note: Disable bail needs to be supported by the test runner plugin in order to work. All official test runner plugins (@stryker-mutator/xxx-runner) support this feature except for Jest. Jest always runs without --bail (see #11766) inside Stryker, however it will report only the first failing test when disableBail=false and all failing tests when disableBail=true

disableTypeChecks [boolean | string]

Default: "{test,src,lib}/**/*.{js,ts,jsx,tsx,html,vue}"
Command: none
Config file: "disableTypeChecks": false

Set to 'true' to disable type checking, or 'false' to enable it. For more control, configure a pattern that matches the files of which type checking has to be disabled. This is needed because Stryker will create (typescript) type errors when inserting the mutants in your code. Stryker disables type checking by inserting // @ts-nocheck atop those files and removing other // @ts-xxx directives (so they won't interfere with @ts-nocheck). The default setting allows these directives to be stripped from all JavaScript and friend files in lib, src and test directories.

dryRunOnly [boolean]

Default: false
Command line: --dryRunOnly
Config file: "dryRunOnly": false

Execute the initial test run only without doing actual mutation testing. Dry run only will still mutate your code before doing the dry run without those mutants being active, thus can be used to test that StrykerJS can run your test setup. This can be useful, for example, in CI pipelines.

dryRunTimeoutMinutes [number]

Default: 5
Command line: --dryRunTimeoutMinutes 5
Config file: "dryRunTimeoutMinutes": 5

Use this option to configure an absolute timeout for the initial test run. Since it can take a while we use minutes as time unit.

fileLogLevel [string]

Default: off
Command line: --fileLogLevel info
Config file: "fileLogLevel": "info"

Set the log level that Stryker uses to write to the "stryker.log" file. Possible values: off, fatal, error, warn, info, debug and trace

force [boolean]

Default: false
Command line: --force
Config file: "force": true

Run all mutants, even if incremental is provided and an incremental file exists. Can be used to force a rebuild of the incremental file. See incremental

ignorePatterns [string[]]

Default: []
Command line: --ignorePatterns dist,coverage
Config file: "ignorePatterns": ["dist", "coverage"]

Specify patterns to files or directories that are not used to run your tests and thus should not be copied to the sandbox directory for mutation testing. Each pattern in this array should be a .gitignore-style glob pattern.

This should only be used in cases where you experience a slow Stryker startup, because too many (or too large) files are copied to the sandbox that are not needed to run the tests. For example, image or movie directories. This option has no effect when used in combination with --inPlace.

These patterns are always ignored: ['node_modules', '.git', '/reports' '*.tsbuildinfo', '/stryker.log', '.stryker-tmp']. Because Stryker always ignores these, you should rarely have to adjust the "ignorePatterns" setting at all. If you want to undo one of these ignore patterns, you can use the ! prefix, for example: ['!node_modules'].

If a glob pattern starts with /, the pattern is relative to the current working directory. For example, /foo.js matches to foo.js but not subdir/foo.js.

When using the command line, the list can only contain a comma separated list of globbing expressions.

ignoreStatic [boolean]

Default: false
Command line: --ignoreStatic
Config file: "ignoreStatic": true

Static mutants are mutants which are only executed during the loading of a file. Testing these mutants come with a big performance penalty. Therefore, it might make sense to ignore static mutants altogether.

For example:

const hi = '👋'; // Mutant 👽 StringLiteral

export function greet(name) {
return `${hi} ${name}`
}

In this example, '👋' on line 1 would be mutated to an empty string by the StringLiteral mutator. However, the mutant is only executed when the file is loaded, making it a static mutant. It is impossible to measure the exact code coverage per test for the mutant. Therefore, Stryker would default to running all tests.

Note: Enabling --ignoreStatic requires "coverageAnalysis": "perTest", because detecting which mutant is static is done during the initial test run and needs per test coverage analysis.

incremental [boolean]

Default: false
Command line: --incremental
Config file: "incremental": true

Enable 'incremental mode'. Stryker will store results in a file and use that file to speed up the next --incremental run. See incremental for more details.

incrementalFile [string]

Default: "reports/stryker-incremental.json"
Command line: --incrementalFile reports/stryker-incremental-alternative.json
Config file: "incrementalFile": "reports/stryker-incremental-alternative.json"

Specify the file to use for incremental mode. See incremental for more details.

inPlace [boolean]

Default: false
Command line: --inPlace
Config file: "inPlace": true

Determines whether or not Stryker should mutate your files in place. Note: mutating your files in place is generally not needed for mutation testing, unless you have a dependency in your project that is really dependent on the file locations (like "app-root-path" for example).

When true, Stryker will override your files, but it will keep a copy of the originals in the temp directory (using tempDirName) and it will place the originals back after it is done.

When false (default) Stryker will work in the copy of your code inside the temp directory.

logLevel [string]

Default: info
Command line: --logLevel info
Config file: "logLevel": "info"

Set the log level that Stryker uses to write to the console. Possible values: off, fatal, error, warn, info, debug and trace

Note: Test runners are run as child processes of the Stryker Node process. All output (stdout) of the testRunner is logged as trace. Thus, to see logging output from the test runner set the logLevel to all or trace.

maxConcurrentTestRunners (DEPRECATED)

DEPRECATED. Please use concurrency instead.

maxTestRunnerReuse [number]

Default: 0
Command line: --maxTestRunnerReuse 20
Config file: "maxTestRunnerReuse": 20

Restart each test runner worker process after n runs. Not recommended unless you are experiencing memory leaks that you are unable to resolve. Configuring 0 here means infinite reuse.

mutate [string[]]

Default: ['{src,lib}/**/*.js?(x)', '!{src,lib}/**/__tests__/**/*.js?(x)', '!{src,lib}/**/?(*.)+(spec|test).js?(x)', '!{src,lib}/**/*+(Spec|Test).js?(x)']
Command line: [--mutate|-m] src/**/*.js,a.js
Config file: "mutate": ["src/**/*.js", "a.js"]

With mutate you configure the subset of files to be mutated. These should be your production code files, and definitely not your test files. The default will try to guess your production code files based on sane defaults. It reads like this:

  • Include all js-like files inside the src or lib dir
    • Except files inside __tests__ directories and file names ending with test or spec.

It is possible to specify exactly which code blocks to mutate by means of a mutation range. This can be done postfixing your file with :startLine[:startColumn]-endLine[:endColumn]. Some examples:

  • "src/app.js:1-11" will mutate lines 1 through 11 inside app.js.
  • "src/app.js:5:4-6:4" will mutate from line 5, column 4 through line 6 column 4 inside app.js (columns 4 are included).
  • "src/app.js:5-6:4" will mutate from line 5, column 0 through line 6 column 4 inside app.js (column 4 is included).

Note: It is not possible to combine mutation range with a globbing expression in the same line.

mutator [MutatorDescriptor]

Default: {}
Command line: none
Config file: "mutator": { "plugins": ["classProperties"], "excludedMutations": ["StringLiteral"] }

  • plugins: allows you to override the default babel plugins to use for JavaScript files. By default, Stryker uses a default list of babel plugins to parse your JS file. It also loads any plugins or presets you might have configured yourself with .babelrc or babel.config.js files. In the rare situation where the plugins Stryker loads conflict with your own local plugins (for example, when using the decorators and decorators-legacy plugins together), you can override the plugins here to [].
  • excludedMutations: allow you to specify a list of mutator names to be excluded (ignored) from the test run. See Disable mutants for more options of how to disable specific mutants.

Note: prior to Stryker version 4, the mutator also needed a name (or be defined as string). This is removed in version 4. Stryker now supports mutating of JavaScript and friend files out of the box, without the need for a mutator plugin.

plugins [string[]]

Default: ['@stryker-mutator/*']
Command line: --plugins @stryker-mutator/jasmine-framework,@stryker-mutator/karma-runner
Config file: "plugins": ["@stryker-mutator/jasmine-framework", "@stryker-mutator/karma-runner"]

With plugins, you can add additional Node modules for Stryker to load (using import). By default, all node_modules starting with @stryker-mutator/* will be loaded, so you would normally not need to specify this option. These modules should be installed right next to stryker. For a current list of plugins, you can consult npm or use one of the officially supported plugins.

reporters [string[]]

Default: ['clear-text', 'progress', 'html']
Command line: --reporters clear-text,progress,dots,dashboard,html,json
Config file: "reporters": ["clear-text", "progress", "dots", "dashboard", "html", "json"]

With reporters, you can set the reporters for Stryker to use. These reporters can be used out of the box: html, json, progress, clear-text, dots, dashboard and event-recorder. By default, clear-text, progress, html are active if no reporters are configured. See reporter plugins for a full description of each reporter.

The html reporter allows you to specify an output folder. This defaults to reports/mutation/html. The config for your config file is: htmlReporter: { fileName: 'mypath/reports/stryker.html' } (since Stryker v6).

The json reporter allows specifying an output file name (may also contain a path). The config for your config file is: jsonReporter: { fileName: 'mypath/reports/mutation.json' }

The clear-text reporter supports three additional config options:

  • allowColor to use cyan and yellow in printing source file names and positions. This defaults to true, so specify as clearTextReporter: { allowColor: false }, to disable if you must.
  • logTests to log the names of unit tests that were run to allow mutants. By default, only the first three are logged. The config for your config file is: clearTextReporter: { logTests: true },
  • maxTestsToLog to show more tests that were executed to kill a mutant when logTests is true. The config for your config file is: clearTextReporter: { logTests: true, maxTestsToLog: 7 },

The dashboard reporter sends a report to https://dashboard.stryker-mutator.io, enabling you to add a mutation score badge to your readme, as well as hosting your html report on the dashboard. It uses the dashboard.* configuration options.

symlinkNodeModules [boolean]

Default: true
Command line: none
Config file: "symlinkNodeModules": true

The symlinkNodeModules value indicates whether Stryker should create a symbolic link to your current node_modules directory in the sandbox directories. This makes running your tests by Stryker behave more like your would run the tests yourself in your project directory. Only disable this setting if you really know what you are doing.

For example, Jest expects any plugins to be located at "./node_modules/..." in the Sandbox directory. Another example can be running karma tests where you specify files from the 'node_modules/angular/...'. Without symlinking the node_modules directory this would not be possible.

Stryker will look for the node_modules directory to use in the current basePath (or current working directory) and its parent directories.

tempDirName [string]

Default: '.stryker-tmp'
Command line: --tempDirName .stryker-tmp
Config file: "tempDirName": '.stryker-tmp'

Choose a different temp dir that Stryker uses for mutation testing. This directory will contain copies of your source code during a mutation test run. It will be created if it not exists and is entirely deleted after a successful run, so change this with caution.

It is advised to use a directory inside the directory that holds your repository. This way node_modules are resolved as expected. Be sure to not check-in your chosen temp directory in your .gitignore file.

testFramework (DEPRECATED)

Note: Use of "testFramework" is no longer needed. You can remove it from your configuration. Your test runner plugin now handles its own test framework integration

testRunner [string]

Default: 'command'
Command line: --testRunner karma
Config file: "testRunner": "karma"

With testRunner you specify the test runner that Stryker uses to run your tests. The default value is command. The command runner runs a configurable bash/cmd command and bases the result on the exit code of that program (0 for success, otherwise failed). You can configure this command via the config file using the commandRunner: { command: 'npm run mocha' }. It uses npm test as the command by default.

The command test runner can be made to work in any use case, but comes with a performance penalty, as Stryker cannot do any optimizations and just runs all tests for all mutants. If possible, you should try to use one of the test runner plugins that hook into your test runner of choice. For example: install and use the @stryker-mutator/karma-runner to use karma as a test runner.

testRunnerNodeArgs [string[]]

Default: []
Command line: --testRunnerNodeArgs "--inspect-brk --cpu-prof"
Config file: "testRunnerNodeArgs": ["--inspect-brk", "--cpu-prof"]

Configure arguments to be passed as exec arguments to the test runner child process. For example, running Stryker with --timeoutMS 9999999 --concurrency 1 --testRunnerNodeArgs "--inspect-brk" will allow you to debug the test runner child process. See execArgv of child_process.fork.

thresholds [object]

Default: { high: 80, low: 60, break: null }
Command line: none
Config file: "thresholds": { "high": 80, "low": 60, "break": null }

Description Specify the thresholds for mutation score.

  • mutation score >= high: Awesome! Reporters should color this green and happy.
  • high > mutation score >= low: Warning! Reporters should color this orange/yellow. Watch yourself!
  • mutation score < low: Danger! Reporters should color this in red. You're in danger!
  • mutation score < break: Error! Stryker will exit with exit code 1, indicating a build failure. No consequence for reporters, though.

It is not allowed to only supply one value of the values (it's all or nothing). However, high and low values can be the same, making sure colors are either red or green. Set break to null (default) to never let your build fail.

timeoutFactor [number]

Default: 1.5
Command line: --timeoutFactor 1.5
Config file: "timeoutFactor": 1.5

See Timeout in milliseconds.

timeoutMS [number]

Default: 5000
Command line: --timeoutMS 5000
Config file: "timeoutMS": 5000

When Stryker is mutating code, it cannot determine indefinitely whether a code mutation results in an infinite loop (see Halting problem). In order to battle infinite loops, a test run gets killed after a certain period of time. This period is configurable with two settings: timeoutMS and timeoutFactor. To calculate the actual timeout in milliseconds the, following formula is used:

timeoutForTestRunMs = netTimeMs * timeoutFactor + timeoutMS + overheadMs

Both netTimeMs and overheadMs are calculated during the initial test run. They are logged on info level. For example when overheadMs is 92 and netTimeMs is 5: Initial test run succeeded. Ran 6 tests in 4 seconds (net 5 ms, overhead 92 ms).

With timeoutFactor you can configure the allowed deviation relative to the time of a normal test run. Tweak this if you notice that mutants are prone to creating slower code, but not infinite loops. timeoutMS lets you configure an absolute deviation. Use it, if you run Stryker on a busy machine and you need to wait longer to make sure that the code indeed entered an infinite loop.

transpilers (DEPRECATED)

Note: Support for "transpilers" plugins is removed since Stryker 4. You can now configure your own buildCommand