Mutation Testing with Stryker

Relevant source files

The following files were used as context for generating this wiki page:

• stryker.config.json
• package.json
• README.md
• CLAUDE.md
• test/basic.test.ts

Mutation testing is a fault-injection technique used in the spoof project to evaluate the effectiveness of the existing test suite. By introducing small, intentional changes (mutants) into the TypeScript source code, the system verifies whether the current tests are robust enough to detect and "kill" these mutants. If a mutant survives, it indicates a gap in test coverage or logic verification.

The project utilizes Stryker Mutator integrated with the Vitest test runner. This process ensures that tests do not just pass, but are actually capable of catching regressions and logical errors in core modules such as MAC address normalization, randomization, and platform-specific interface handling.

Sources: README.md:214-218, CLAUDE.md:38

System Architecture and Workflow

The mutation testing workflow involves the Stryker core engine, a dedicated Vitest runner plugin, and the project's source files. Stryker generates mutants based on the src/**/*.ts files, excluding type definitions, and executes the test suite for each mutant to determine its status.

The diagram shows the lifecycle of a mutant from generation to reporting. Sources: stryker.config.json:1-15, package.json:28-31

Key Components

• Stryker Core: Orchestrates the mutation process and manages concurrency.
• Vitest Runner: Executes the unit tests defined in test/*.test.ts against mutated code.
• Reporters: Provides feedback through multiple channels including HTML dashboards and console output.

Sources: stryker.config.json:2-12

Configuration and Integration

The behavior of the mutation testing engine is defined in stryker.config.json. The configuration specifies which files to target, how to run tests, and how to optimize performance.

Configuration Specification

Option	Value	Description
testRunner	vitest	Uses Vitest as the primary execution engine for tests.
mutate	["src/**/*.ts", "!src/types.ts", "!src/**/*.d.ts"]	Targets all TypeScript logic while ignoring type-only files.
coverageAnalysis	perTest	Optimizes performance by only running tests that cover the mutated code.
concurrency	4	Number of concurrent workers allowed for mutation testing.
timeoutMS	10000	Maximum time allowed for a single test run before it is considered timed out.

Sources: stryker.config.json:1-15

Execution Commands

Mutation testing can be triggered through defined npm/yarn scripts. The project provides aliases for running Stryker through the CLI.

• yarn mutation: Runs the full mutation testing suite using npx stryker run.
• yarn stryker: An alias for the same command.

Sources: package.json:85-86, CLAUDE.md:38

Test Effectiveness and Reporting

The results of a mutation run are aggregated into reports that help developers identify weak points in the test/ directory.

Reporting Formats

The system generates reports in three formats:

1. HTML: A detailed visual report located at reports/mutation/mutation.html.
2. Clear-text: A summary printed directly to the terminal for quick review.
3. Progress: Real-time feedback in the CLI during the mutation run.

Sources: stryker.config.json:10-14, README.md:218

The sequence diagram illustrates the interaction between Stryker and the Vitest runner during a mutation analysis cycle. Sources: stryker.config.json:2-15, test/basic.test.ts:1-10

Implementation Details

The mutation engine targets specific logic within the project's core files. For instance, in src/index.ts, mutants might be injected into regex patterns like MAC_ADDRESS_RE or CISCO_MAC_ADDRESS_RE to ensure that the normalization logic in test/basic.test.ts correctly identifies invalid formats.

Example Mutation Targets

• Normalization Logic: Changing string manipulation in spoof.normalize().
• Randomization: Altering the vendor prefix selection in spoof.randomize().
• Platform Detection: Mutating process.platform checks to ensure platform-specific branches are adequately tested.

Sources: stryker.config.json:5-9, test/basic.test.ts:10-30

Conclusion

Mutation testing with Stryker provides a critical layer of quality assurance for the spoof project. By going beyond simple line coverage and measuring the "kill rate" of mutants, the project ensures that its network interface management and MAC address manipulation logic are backed by a truly rigorous test suite. Developers should regularly run yarn mutation and review the HTML reports to maintain high code reliability across macOS, Linux, and Windows platforms.

Sources: README.md:214-220, CLAUDE.md:38