How to use incremental mutation tests

Use the incremental mutation command to reuse Stryker results from a local report or the latest successful main workflow.

Run mutation tests locally

Run the command for the application that you changed:

nx run @tillo/scout:test:mutation:incremental
nx run @eos/harbourmaster:test:mutation:incremental
nx run @eos/figma-mcp:test:mutation:incremental

Nx restores reports/stryker-incremental.json when it reuses a cached task result. Otherwise, the package script checks that report first. If the report does not exist, the script tries to download the latest successful main workflow artifact. The script continues when GitHub access or the artifact is not available.

When no report exists, Stryker performs a full mutation run. It then writes a local report for later runs.

The local report is ignored by Git. Do not add it to a commit.

The download uses the GitHub CLI. Authenticate with GitHub before you use the shared main report:

gh auth status

The helper uses TilloTech/eos, mutation-baseline.yml, and main by default. Set these variables when you need another source:

STRYKER_BASELINE_REPOSITORY=owner/repository
STRYKER_BASELINE_WORKFLOW=mutation-baseline.yml
STRYKER_BASELINE_BRANCH=main
STRYKER_BASELINE_ARTIFACT=stryker-scout-incremental

Add --skip-nx-cache to the Nx command when you need to run the script again, such as after a baseline source override.

Run a full mutation test

Use the full command after a dependency, test runner, or Stryker configuration change:

nx run @tillo/scout:test:mutation:full
nx run @eos/harbourmaster:test:mutation:full
nx run @eos/figma-mcp:test:mutation:full

This command uses --force with --incremental. Stryker reruns all mutants and refreshes the incremental report.

Understand the CI workflow

The mutation job restores separate reports for Scout, Harbourmaster, and Figma MCP. The cache prefix includes the runner operating system, lockfile, Node.js version, setup action, Stryker configuration, test runner configuration, and TypeScript configuration. Stryker compares the source and test files with the restored report.

nx-set-shas selects the last successful CI commit. nx affected uses the Nx project graph to select each incremental mutation target. Pull requests can restore trusted reports from main.

Only a successful main run or scheduled run saves a cache. Pull request runs do not update the trusted reports. Successful trusted runs also upload each report as a workflow artifact. Developers can download these artifacts through the local command.

The mutation-baseline.yml workflow runs a full mutation test every Monday at 02:00 UTC. This refreshes the reports and checks for drift in incremental state.

Recover from a stale report

Run the full command if a report is corrupt, stale, or no longer useful:

nx run @tillo/scout:test:mutation:full
nx run @eos/harbourmaster:test:mutation:full
nx run @eos/figma-mcp:test:mutation:full

Run the full command after these changes:

• dependency versions;
• Stryker or Vitest versions;
• Stryker configuration;
• Vitest or TypeScript configuration;
• environment or snapshot behaviour.

If no baseline is available in CI, the mutation job performs a full run. A cache miss or an expired artifact does not fail the job by itself.