How stryker-mutator/stryker-js works
Project type and purpose
• This is StrykerJS: an open-source, monorepo-based mutation-testing framework for JavaScript and TypeScript.
• It bundles a pluggable core engine, instrumentation and mutator libraries, adapters (“runners”) for various test frameworks, CLI tools, and helper utilities.
High-level architecture
At the highest level, Stryker executes as a CLI that:
a. Loads your configuration (via config reader).
b. Instantiates a dependency-injection container.
c. Loads plugins (instrumenters, mutators, test-runner adapters, reporters).
d. Orchestrates a pipeline of executors (prepare, instrument, dry-run, mutation test).
e. Spawns sandboxed child processes to run tests.
f. Aggregates results and emits reports.
Main components
A. CLI entrypoint (“stryker” / packages/core/bin/stryker.js)
– Reads arguments, locates a config file (default or stryker.conf.js)
– Delegates to the Core Orchestrator
B. Config Reader (packages/core/src/config)
– Merges defaults, CLI overrides, and config file
C. DI Container & Plugin Loader (packages/core/src/di, packages/api/src/plugin)
– Registers tokens and loads plugins by kind (instrumenter, runner, reporter, checker)
D. Core Orchestrator (packages/core/src/process)
– Sequential executors:
1. PrepareExecutor: validation, input-file reading
2. InstrumenterExecutor: calls Instrumenter
3. DryRunExecutor: runs tests once without mutants
4. MutationTestExecutor: loops over mutants, runs tests per mutant
E. Instrumenter (packages/instrumenter)
– Parses source files, applies mutator plugins, generates instrumented code
F. Sandbox (packages/core/src/sandbox)
– Creates child-process or worker sandboxes for isolation
– Preprocesses files (e.g., ts-config rewriting)
G. Test-Runner Adapters (packages/*-runner)
– Jasmine, Mocha, Jest, Karma, Tap, Cucumber, Vitest, etc.
– Each plugin wraps the external framework, instruments it for mutation analysis, reports back test results
H. Checker (packages/typescript-checker)
– Optionally type-checks sources to prune impossible mutations
I. Reporter Plugins (packages/core/src/reporters, plus external dashboard CI plugins)
– Console reporters (clear-text, progress, dots)
– HTML, JSON, dashboard back-ends
J. Utilities (packages/util, packages/api, logging)
– Shared logging infrastructure (packages/core/src/logging, packages/api/src/logging)
– Common helpers (deep-merge, child-process handling, schema validation)
Relationships and data flow
1. User invokes CLI → Core Orchestrator
2. Orchestrator asks Config Reader → Combined options
3. DI Container + Plugin Loader → Instantiated plugins: instrumenter, mutators, test runners, reporters, checker
4. PrepareExecutor → reads file system (packages/core/src/fs)
5. InstrumenterExecutor → Instrumenter produces instrumented code artifacts
6. DryRunExecutor → Sandbox + Test-Runner → “baseline” test results
7. MutationTestExecutor → For each mutant:
• Mutant placement via instrumenter
• Tests run in Sandbox + Test-Runner
• Test-Runner reports pass/fail back
8. Reporter plugins subscribe to events (dry-run completed, mutation test ready) and render output
Architectural patterns and design principles
• Modular Plugin Architecture: everything is a plugin (instrumenters, runners, reporters) loaded via DI
• Executor Pipeline: linear sequence of stages, each stage injection-based
• Sandbox Isolation: child processes to reliably reset environment per mutant/test run
• Monorepo with Strict Boundaries: each packages/* has its own tests, config, and published artifact
• Separation of Concerns:
– Core orchestrator concerns vs. test-framework adapters vs. code mutation logic