stryker-mutator/stryker-js
github.com/stryker-mutator/stryker-js ↗ · 2239 files · 5.3 MB
StrykerJS Professor X: For someone who hates mutants...
Overview
StrykerJS is a mutation-testing framework for developers assessing whether JavaScript and TypeScript tests detect deliberate changes to production code. It instruments multiple mutants into source files, runs baseline tests, then schedules individual mutants through configurable test runners and optional checkers. This monorepo contains the public plugin API, execution engine, language instrumenter, framework adapters, reporting tools, and integration fixtures; its distinctive mechanisms include per-test mutant coverage, incremental result reuse, and an editor-facing mutation server.
System map
The repository builds and publishes a family of Node.js packages coordinated by pnpm, Lerna, and TypeScript project references. Core owns the CLI and execution lifecycle, while the API and instrumenter define integration contracts and source transformation. Runtime work crosses parent-process, worker-process, filesystem, and optional network boundaries. Persistence consists of project copies, backups, and report files in the inspected paths.
- The executable sets process.title to 'stryker' and invokes StrykerCli.run(); the core package exposes its compiled index and installs bin/stryker.js as the stryker command.
- The parent is a private ESM package requiring Node >=22 and pnpm@11.5.1; pnpm workspaces include packages, e2e, and individual e2e fixture packages.
- TypeScript project references separate core, API, util, instrumenter, create-stryker, eight runner packages, typescript-checker, and test-helpers.
- Stryker.run executes preparation, instrumentation, baseline testing, and mutation execution sequentially through typed-inject contexts; runMutationTest disposes its root injector in finally.
- The public API exports separate check, core, ignore, logging, plugin, report, and test-runner entrypoints rather than one root export.
- ChildProcessProxy forks a worker with configurable Node arguments and inherited environment, then sends options, file descriptions, plugin paths, module/export identity, and working directory through IPC.
- ProjectFile caches original and current content independently; FileSystem forwards Node filesystem operations through an RxJS queue limited to 256 concurrent actions.
- Root build generates schemas/types before tsc -b, tests run through Lerna, and tag-triggered publishing builds packages before lerna publish from-git with npm provenance permission.
Feature catalog
The main user surfaces are CLI commands, a programmatic mutation run, reports, and a mutation-server protocol. Users can select files and source ranges, choose framework integrations, suppress mutants, and control baseline or incremental execution. Reporter choices cover terminal feedback, local artifacts, and dashboard publication. Framework UI examples are integration targets rather than the central product interface.
- stryker run accepts a configuration path and invokes Stryker.runMutationTest; stryker init creates an initializer and disposes its injector after initialization.
- serve supports stdio or socket channels, socket address/port options, and forwarded run options; runServer remains a deprecated socket-server command.
- Project selection supports mutation globs, exclusions, explicit test-file patterns, and line/column mutation ranges; unmatched explicit test patterns produce warnings.
- Language dispatch recognizes JS/JSX/MJS/CJS, TS/MTS/CTS, TSX, Vue/HTML/HTM, and Svelte; unknown extensions produce a parser-registration error.
- Workspace integrations include Cucumber, Jasmine, Jest, Karma, Mocha, TAP, Vitest, and TypeScript checking; the built-in command runner defaults conceptually to npm test and rejects explicit testFiles.
- Mutants can be suppressed through excludedMutations, Stryker disable comments, or Ignore plugins; suppressed mutants remain visible in reports without contributing to the score.
- Execution supports dryRunOnly, allowEmpty, coverage-based test selection, ignoreStatic, and incremental result reuse; force prevents reuse of existing mutant statuses.
- Built-in reporters include clear-text, progress, append-only progress, dots, event-recorder, HTML, JSON, and dashboard; dashboard reportType selects a full report or mutation score, and thresholds.break can fail the run.
Data flow
Configuration and filesystem selection establish the project model before source transformation begins. Instrumentation produces modified files and mutant metadata, while the baseline test runner supplies test results, coverage, and timing. The planner converts these inputs into early results or executable run options, and the executor streams outcomes into reporting. Reports preserve original source and test relationships, and incremental mode feeds that persisted information into later planning.
- ConfigReader loads a discovered or explicit JSON/JavaScript configuration, deep-merges CLI options with precedence, and validates it; preparation adds plugin schemas, validates again, then deep-freezes options.
- ProjectReader crawls from process.cwd(), applies ordered ignore rules, resolves mutation/test descriptions, reads an optional incremental report, and constructs Project.
- ProjectFile.toInstrumenterFile supplies name, mutation scope, and current text; Instrumenter parses each file, transforms its AST, prints instrumented text, and returns files plus API mutants.
- MutantInstrumenterExecutor stores generated text in ProjectFile, runs preprocessors, initializes the checker pool, then initializes Sandbox; unchanged sandbox files are copied while changed text is written.
- DryRunExecutor passes sandbox mutation/test paths, coverage mode, bail preference, and timeout to dryRun; it remaps returned test filenames and derives net time and nonnegative overhead.
- MutantTestPlanner produces covered-test filters or full-test plans; timeout equals timeoutFactor × netTime + timeoutMS + overhead, hitLimit is 100 × baseline hits, and hot swapping requires a filter and nonstatic coverage.
- Mutation execution separates early results, checker failures, empty-filter NoCoverage results, and test-runner outcomes, merges them into an array, and calls reportAll before reporter.wrapUp.
- Report assembly remaps test IDs, includes original mutation/test sources, config, cwd, thresholds, and framework metadata; incremental loading converts report positions back to zero-based internal coordinates before diffing.
Behavior traces
The inspected flows cover CLI startup and preparation, mutation execution, incremental persistence/reuse, and server discovery/execution. These traces follow concrete function calls and preserve conditions that change the route through execution. Baseline failures stop mutation testing, while ignored or cached mutants bypass runner execution. Cleanup and asynchronous reporter completion are explicit parts of the lifecycle.
- Startup follows bin/stryker.js → StrykerCli.run → run action → Stryker.runMutationTest → logging/injector setup → Stryker.run → PrepareExecutor.execute.
- Preparation follows ConfigReader.readConfig → PluginLoader.load → MetaSchemaBuilder.buildMetaSchema → OptionsValidator.validate → ProjectReader.read → TemporaryDirectory.initialize; an empty project throws ConfigError.
- Instrumentation follows readFilesToMutate → Instrumenter.instrument → writeInstrumentedFiles → preprocess.preprocess → checkerPool.init → Sandbox.init; Sandbox fills files, runs buildCommand, then creates dependency symlinks.
- Baseline execution schedules executeDryRun → testRunner.dryRun → capabilities → validateResultCompleted → path remapping → timing calculation → onDryRunCompleted; failed tests, errors, timeouts, or disallowed empty runs stop progression.
- Primary mutation execution follows makePlan → executeEarlyResult → executeCheck → executeNoCoverage → executeRunInTestRunner → reportAll → wrapUp; dryRunOnly and allowed empty baselines return before this chain.
- Incremental reuse follows ProjectReader.readIncrementalReport → MutantTestPlanner.incrementalDiff/readAllOriginalFiles → IncrementalDiffer.diff → planMutant; eligible old statuses become early results unless force is enabled.
- Persistence follows reportOne accumulation → reportAll → mutationTestReport → metrics calculation → onMutationTestReportReady → optional writeIncrementalReport → threshold evaluation; interruption saves partial results only when incremental is enabled and results exist.
- Server start installs framed JSON-RPC methods; configure records a config path, discover prepares and instruments selected files, and mutationTest calls Stryker.run with a reporter override that emits progress notifications before an empty final result.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage is asserted. Core uses compiled Mocha tests with Chai, Sinon, promise assertions, and snapshots. The inspected suites exercise orchestration branches, incremental reuse, HTML serialization, and real server transports, while e2e fixtures cover several frontend/framework configurations. This inventory is bounded and does not establish exhaustive coverage or the absence of additional tests.
- Core test runs c8 over unit and integration scripts; Mocha targets dist/test, uses a 60-second integration timeout, loads compiled setup, and forbids focused tests when CI is set.
- Core setup installs Sinon-Chai, Chai-as-promised, and Chai-Jest snapshots; after each test it disposes/reset injectors, restores Sinon, and restores cwd.
- MutationTestExecutor unit tests explicitly assert that ignored mutants skip checkers/runners and empty test filters produce NoCoverage without mutantRun.
- IncrementalDiffer tests distinguish reuse after test removal/addition and invalidate Killed results when the killing test disappears; an unchanged killer also supports static-mutant reuse.
- HTML reporter tests check serialized report output, splitting of script tags in embedded source, and wrapUp rejection when writing fails; these inspected assertions use a write stub rather than proving browser execution safety.
- Server integration tests spawn the CLI over socket and stdio and share configure/discover/mutation assertions; they also exercise parallel mutation requests and temporary-directory cleanup.
- The e2e harness filters fixture names, supports concurrency/resume, skips incompatible Node/platform fixtures, and retries per fixture; inspected Vite fixtures include Vue, Svelte/jsdom, and React browser-mode Chromium.
- CI config schedules build/lint/test on Node 22/24 across Ubuntu/Windows and separate e2e jobs; mutation CI names selected package scopes, while performance runs are manually triggered and upload report artifacts.
Risk map
The inspected sensitive boundaries are imported project code, shell commands, inherited worker environments, filesystem writes, JSON-RPC, and dashboard uploads. The sandbox is a project execution directory with dependency links and an optional in-place mode. Observations here describe source behavior and review hotspots, not confirmed vulnerabilities. Partial inspection does not establish a repository-wide absence of authentication, validation, or security tests.
- JavaScript configuration and plugin descriptors execute through dynamic module imports, including resolved absolute/relative paths; configuration or plugin selection therefore crosses a trusted-code execution boundary.
- CommandTestRunner passes configured command text to child_process.exec with the current environment; Sandbox also executes buildCommand. These are intentional shell/process execution surfaces requiring trusted project configuration.
- inPlace selects cwd, backs up changed files, overwrites originals, and restores backups on disposal; original-file recovery is a high-impact lifecycle boundary.
- Sandbox shares node_modules through symlinks and may locate dependencies in parent directories, while worker forks inherit process.env; the inspected mechanisms provide execution separation without removing host dependencies or environment access.
- The inspected server start path registers configure/discover/mutationTest directly and accepts socket connections without an authentication check there; CLI defaults to localhost but permits an address override.
- Incremental reports are JSON-parsed without schema/version validation, explicitly noted by a TODO, and their configured path is written with recursive parent-directory creation; malformed cache input can propagate errors beyond simple parsing.
- Full dashboard uploads can include original sources, tests, configuration, and projectRoot; DashboardReporterClient sends an X-Api-Key from STRYKER_DASHBOARD_API_KEY to configured baseUrl and trace-logs the serialized report.packages/core/src/reporters/dashboard-reporter/dashboard-reporter.ts#L56-L66packages/core/src/reporters/mutation-test-report-helper.ts#L243-L254packages/core/src/reporters/dashboard-reporter/dashboard-reporter-client.ts#L41-L57packages/core/src/reporters/dashboard-reporter/dashboard-reporter-client.ts#L73-L82
- Vitest integration branches on framework versions, accesses ctx.state internals, and clears filesMap as an acknowledged hack; baseline path remapping separately assumes type-check suppression shifts test lines by exactly one.
Extension points
The primary supported extension mechanism is a typed plugin contract for runners, checkers, reporters, and ignorers. Plugin modules contribute declarations and optional validation schemas, and typed-inject constructs their instances. Internal registries and factory functions offer separate seams for mutation operators, parsers, preprocessors, and initialization presets. These internal seams should not be confused with public plugin categories.
- PluginInterfaces maps Reporter, TestRunner, Checker, and Ignore kinds to their contracts; declareClassPlugin, declareFactoryPlugin, and declareValuePlugin construct typed declarations.
- PluginLoader accepts module names, file paths/URLs, and simple wildcard expressions, collecting strykerPlugins and strykerValidationSchema; preparation combines configured, framework, reporter, and appendPlugins descriptors.
- PluginCreator resolves names case-insensitively within a kind and invokes the factory/class through the injector or returns a value; missing registrations produce diagnostic errors listing loaded plugins.
- A TestRunner implements capabilities, dryRun, and mutantRun with optional init/dispose; createTestRunnerFactory wraps plugin runners with retry, reload, reuse-limit, timeout, and child-process layers.
- A Checker implements init and check plus optional group; MutationTestExecutor applies configured checkers in sequence, buffering/grouping mutants and converting failed checks to early results.
- Reporter hooks cover baseline completion, plan readiness, individual mutants, final report/metrics, and asynchronous wrapUp; the built-in reporter list demonstrates class and factory registrations.
- NodeMutator supplies a name, iterable AST replacements, and optional subtree filter; allMutators registers operators, and babelTransform invokes filters on exit before mutant placement.
- Additional formats require parser dispatch changes; preprocessing composes DisableTypeChecksPreprocessor and TSConfigPreprocessor, while createInitializers explicitly registers Angular, React, Svelte, and Vue presets.
Contributor handoff
Begin with the affected package and its API contract, then follow the execution stage that owns the behavior. Tests and CI were inspected, not executed, and this brief is a bounded source inventory rather than a complete coverage assessment. Future executable work should use repository scripts and compile current sources before selecting tests that run from dist. Preserve cleanup, coordinate conversion, runner activation, and report compatibility when making small changes.
- Use package.json and pnpm-workspace.yaml as the package-manager authority, then read the affected package manifest; the contribution guide states that package-local tests are faster and assume compiled sources.
- For core behavior, read Stryker.run and the four executors before editing: each stage returns an injector containing dependencies needed by the next stage.
- Tests and CI were inspected, not executed for this brief; future authorized verification can begin with core test:unit or test:integration after compilation, using their existing dist/test targets.
- Schema changes should modify source JSON and use the existing generator; it emits src-generated types, marks them generated, and treats default-bearing schema properties as required in generated output.
- Preserve coordinate conventions: mutation-range lines become zero-based, instrumentation shifts lines for Babel, report loading subtracts one from line/column, and server range ends adjust protocol columns.
- Runner changes must preserve static/runtime activation and reload semantics; the planner permits hot swapping only for filtered nonstatic mutants, while the plugin guide distinguishes activation before versus after environment loading.
- Sandbox and disposal edits require attention to inPlace restoration and error retention: Stryker keeps temporary artifacts after errors unless cleanTempDir is 'always', while Sandbox restores backed-up originals during disposal.
- Use a selected e2e fixture for framework changes and distinguish adapter behavior from orchestration mocks; the harness supports a positional glob, and Vitest's version-dependent pool settings and internal state reset need review when compatibility changes.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 883 | 58% |
| JavaScript | 617 | 40% |
| JSON | 372 | docs/config |
| Markdown | 69 | docs/config |
| HTML | 26 | docs/config |
| Svelte | 13 | 1% |
| Sass | 11 | 1% |
| Vue | 9 | 1% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1240 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/core/ | 88 |
packages/cucumber-runner/ | 59 |
packages/vitest-runner/ | 99 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 1240 |
e2e/ | 850 |
perf/ | 85 |
docs/ | 27 |
.github/ | 10 |
tasks/ | 4 |
.devcontainer/ | 1 |
.travis/ | 1 |
Docs found: CONTRIBUTING.mdREADME.mddocs/config-file.mddocs/configuration.mddocs/cucumber-runner.mddocs/disable-mutants.mddocs/getting-started.mddocs/guides/angular.mddocs/guides/create-a-plugin.mddocs/guides/legacy/stryker-3/angular.md
Package
package.json — stryker-parent, 42 declared dependencies.
@eslint/js@types/chai@types/chai-as-promised@types/chai-jest-snapshot@types/istanbul@types/karma@types/mocha@types/node@types/sinon@types/sinon-chai@types/source-map-support@typescript-eslint/utils
CI & config entrypoints
README.md— Repository readmepackages/vitest-runner/testResources/vi-mock/vite.config.ts— Vite config.github/workflows/performance.yml— GitHub Actions workflow.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/mutation-testing.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflowe2e/test/vue-typescript-vitest/vite.config.ts— Vite confige2e/test/svelte-ts-vitest/vite.config.ts— Vite confige2e/test/svelte-js-vitest/vite.config.js— Vite confige2e/test/svelte-kit-vitest/vite.config.ts— Vite config
Structural health signals
Average score 8.1/10 across 96 analyzed source files; 6 hotspots surfaced.
packages/instrumenter/testResources/instrumenter/perf/benchmark-big.ts— 930 lines, score 5.5 (Large file, Deep nesting)packages/tap-runner/src/tap-test-runner.ts— 266 lines, score 5.7 (Deep nesting, Long function/block)packages/jasmine-runner/typings/jasmine-types.d.ts— 1198 lines, score 6.2 (Large file, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
f2a49ff024372026-09-11 — feat(vitest-runner): report test locations (#6188)e873a24ea7fe2026-09-11 — fix(instrumenter): crash when mutating ts non null expression in babel >= 8 (#6221)f9225709e9d12026-08-31 — chore(deps): update dependency webpack-cli to v7.2.3 (#6206)6a9691578b592026-08-31 — chore(deps): update dependency @vitejs/plugin-react to v6.1.1 (#6204)53accf8faf0d2026-08-31 — chore(deps): update typescript-eslint monorepo to v8.68.0 (#6202)