Skip to content
Mutato Mutato

Getting started

Install

Section titled “Install”

Mutato ships as a .NET global tool. Because .NET 10 packaging is platform-specific, the tool is installed per RID behind the dotnet-mutato manifest package:

Terminal window
dotnet tool install -g dotnet-mutato --prerelease

The optional test-side hooks live in a separate package (see Cooperative hooks):

Terminal window
# added for you by `mutato init`, or reference it manually
dotnet add test/YourProject.Tests package Mutato.Testing --prerelease

Build from source

Section titled “Build from source”

To run against the current source tree instead of a published package:

Terminal window
git clone https://github.com/slang25/mutation-testing-play
cd mutation-testing-play


dotnet pack src/Mutato.Cli -c Release        # -> artifacts/dotnet-mutato.<rid>.*.nupkg
dotnet pack src/Mutato.Testing -c Release    # -> artifacts/Mutato.Testing.*.nupkg (+ Runtime)
dotnet tool install -g --add-source artifacts dotnet-mutato --prerelease

Run it

Section titled “Run it”

From the root of the repository you want to test:

Terminal window
mutato init      # discover the target/test pair, add the Mutato.Testing hooks,
                 # and write .mutato/config.toml
mutato           # your first mutation score

mutato also works without init — the hooks package is optional, and there is nothing to deploy alongside your tests: the runtime is compiled into the instrumented target as injected source.

With no --project/--tests, Mutato reads .mutato/config.toml (or a legacy ./mutation-config.json) if present, otherwise auto-discovers the target and test project pair under the current directory (preferring test projects that reference Mutato.Testing).

If your repo has several plausible pairs, mutato init doesn’t give up — on a terminal it offers them as a ranked pick-list, each row showing why it’s a candidate (“sole reference · name match”) and the full paths of the highlighted one:

mutato · which project should I mutate?
  5 plausible pairs here — none stood out, so take your pick


     mutate              using tests
     Polly               Polly.Specs               sole reference · name match
   ❯ Polly.Core          Polly.Core.Tests          sole reference · name match
     Polly.RateLimiting  Polly.RateLimiting.Tests  referenced · name match


     mutate src/Polly.Core/Polly.Core.csproj
     tests  test/Polly.Core.Tests/Polly.Core.Tests.csproj


  ↑↓ move · type to filter · enter select · esc cancel

Arrow keys move, typing filters, enter picks — and the chosen pair is echoed back as the --project/--tests-project flags that would have skipped the prompt. Piped, in CI, or with --plain, the same shortlist prints as ready-to-paste commands instead.

Explicit invocation

Section titled “Explicit invocation”

You can also point Mutato at specific projects and narrow what it mutates:

Terminal window
mutato \
  --project src/Polly.Core/Polly.Core.csproj \
  --tests-project test/Polly.Core.Tests/Polly.Core.Tests.csproj \
  --filter Polly.Retry.RetryHelper \
  --workers 4 \
  --json report.json \
  --html report.html
  • --filter scopes mutation to a type or namespace prefix — start narrow.
  • --tests-project builds the test project and locates its assembly; pass a prebuilt --tests <tests.dll> to skip the build.
  • --json / --html emit a Stryker-schema report you can open in the standard viewer.

See Configuration for the full set of options and the .mutato/config.toml file format.

From MSBuild

Section titled “From MSBuild”

If your test project references the Mutato.Testing package, a run is also available as an MSBuild target:

Terminal window
dotnet build test/YourProject.Tests /t:Mutate