What this fork is

Ditto is a fork of gtramontina/ooze, whose last release was v0.3.1 in May 2023. All the good ideas here are Guilherme J. Tramontina's, and the licence and copyright stay with him.

The fork exists to push on two things, in this order:

Fast. Mutation testing is usually run in CI, once, on everything. Ditto is built for the other place: inside a TDD loop, on staged changes, while you are still writing the code. That means the target is not throughput on a build server, it is latency on the laptop you are also editing in — and it means deliberately not buying speed with parallelism that makes the machine unusable.

Well made. A fast answer that is wrong is worse than no answer, because you act on it. Ditto treats a misleading verdict as a defect, not a caveat. The prerequisite two sections down — that a failing suite makes every mutant look killed — is the clearest example: it is documented upstream as something to be careful about, and it is on this fork's list to refuse outright.

Performance is the metric

For a library whose reason to exist is being cheap enough to run, "it got slower" is the same statement as "it stopped working". So the cost is recorded rather than remembered:

• perf/baseline.json holds exact counters — files linked per mutant, parses per release, test-command runs per release. Integers, identical on every machine, unaffected by whatever else the machine is doing.
• internal/perfbench enforces them. A counter that grows fails the build. A counter that shrinks also fails the build, until the gain is written down, so an improvement cannot be quietly handed back later.
• Wall clock is measured and reported, never gated. On a real development machine the same workload has varied here by more than fifty percent between runs; a threshold tight enough to catch a regression would fire on the weather, and a gate that cries wolf is a gate people learn to ignore.

Every claim about speed in this repository should come with the number that would disprove it.

Mutation Testing?

Mutation testing is a technique used to assess the quality and coverage of test suites. It involves introducing controlled changes to the code base, simulating common programming mistakes. These changes are, then, put to test against the test suites. A failing test suite is a good sign. It indicates that the tests are identifying mutations in the code—it "killed the mutant". If all tests pass, we have a surviving mutant. This highlights an area with weak coverage. It is an opportunity for improvement.

There are different types of changes that mutation tests can perform. A common collection usually include:

• Changing an operator;
• Replacing a constant;
• Removing a statement;
• Increasing/decreasing numbers;
• Flipping booleans;

Mutations can also be domain/application-specific. Although, these are up to the maintainers of such application to develop.

It is worth mentioning that mutation tests can be quite expensive to run. Especially on larger code bases. And the reason is that for every mutation, on every source file, the entire suite of tests has to run. One can look at the bright side of this and think as an incentive to keep the test suites fast.

Mutation testing is a great ally in developing a robust code base and a reliable set of test suites.

Quick Start

Prerequisites

Make sure the test suite Ditto will run is passing. It no longer has to be taken on trust: Ditto runs the suite once on unmutated code before scoring anything, and refuses the run if it is already red. That guard exists because the alternative was measured — a red baseline used to report 431 of 431 mutants killed in 5.46 seconds, a perfect score for a run that compiled nothing. It costs one invocation per release, never one per mutant.

When Ditto reports that it found a living mutant, it will print a diff of the changes the virus made to the source file. The mutant source is printed using Go's go/format package. This means that, if your source code isn't gofmt'd, the diff may contain some formatting changes that are not relevant to the mutation. This isn't a prerequisite per se, but for a better experience, it is recommended that you run gofmt on your source files.

From the command line

Ditto also runs as a command, which is the shorter way in when what you want is a gate rather than a test:

go install github.com/Disble/ditto/cmd/ditto@latest

ditto run --threshold 0.8                 # mutate the repository
ditto staged --dry                        # what would a staged change cost?
ditto staged --threshold 0.8              # mutate only what it justifies

ditto staged reads the change you have staged and nothing else: which files it touches, which of their bytes, and — the part that is easy to skip — it runs the suite against a checkout of the index, not of your working tree.

That last one is not caution, it is the difference between two answers. Measured on a fixture built for it: with the release pointed at the worktree instead, and one tracked file left dirty and unstaged, seven of eight verdicts moved — a score of 0.13 against 1.00 for the identical eight mutants of an identical file. Checking that the staged files themselves are clean does not cover it, because the file that moved them was never staged.

Policy stays with you: --threshold, --test-command, and --exclude-prefix (repeatable) are yours to set, and Ditto has an opinion about none of them beyond its defaults.

Installation as a library

1. Install ditto:

   go get github.com/Disble/ditto
   

   This pulls the latest version of Ditto and updates your go.mod and go.sum to reference this new dependency.

2. Create a mutation_test.go file in the root of your repository and add the following:

   //go:build mutation
   
   package main_test
   
   import (
   	"testing"
   
   	"github.com/Disble/ditto"
   )
   
   func TestMutation(t *testing.T) {
   	ditto.Release(t)
   }
   

   The build tag is so you can better control when to run these tests (see the next step). This is a test as you'd write any other Go test. What differs is what the test actually does. And this is where it delegates to Ditto, by Releaseing it.

3. Run with:

   go test -v -tags=mutation
   

   This will execute all tests in the current package including the sources tagged with mutation. This assumes that the above is the only test file in the root of your project. If you have other tests, you may want to put the mutation tests in a separate package, under ./mutation for example, and configure Ditto to use .. as the repository root (see WithRepositoryRoot below).

   If -v is enabled, Ditto will also be verbose. To enable Ditto's verbose mode only without the test framework verbosity, use -ditto.v.

   Note printing to stdout while Go tests are running has its intricacies. Running the tests at a particular package (without specifying which test file or subpackages, like ./...), allows for Ditto to print progress and reports as they happen. Otherwise, the output is buffered and printed at the end of the test run and, in some cases, only if a test fails. This is a limitation of Go's testing framework.

Results

Once all tests on all mutants have run, Ditto will print a report with the results. It will also exit with a non-zero exit code if the mutation score is below the minimum threshold (see WithMinimumThreshold below). This is an example of the report, exactly as ditto prints it — the byte-for-byte content of testdata/golden/release.txt, which TestReleaseGolden compares a whole release against on both the ordinary and the gated path. It is text rather than a screenshot for one reason: a screenshot goes stale in silence, and this cannot — if the report changes, the golden test fails.

┃ Releasing Ditto…
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┃ 🧬 Survivors
┠┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
┃ calc/calc.go:12:11 → Arithmetic (- → +)
┃ calc/calc.go:16:41 → Arithmetic (+ → -)
┃ calc/calc.go:8:8 → Comparison (inserts =)
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┃ 🧬 Mutant survived: calc/calc.go:12:11 → Arithmetic
┠┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
┃ --- calc/calc.go (original)
┃ +++ calc/calc.go (mutated with 'Arithmetic')
┃ @@ -9,7 +9,7 @@
┃  		return a - b
┃  	}
┃  
┃ -	return b - a
┃ +	return b + a
┃  }
┃  
┃  // Uncovered is never called, so every mutant of it lives.
┃ 
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┃ 🧬 Mutant survived: calc/calc.go:16:41 → Arithmetic
┠┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
┃ --- calc/calc.go (original)
┃ +++ calc/calc.go (mutated with 'Arithmetic')
┃ @@ -13,4 +13,4 @@
┃  }
┃  
┃  // Uncovered is never called, so every mutant of it lives.
┃ -func Uncovered(a, b int) int { return a + b }
┃ +func Uncovered(a, b int) int { return a - b }
┃ 
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┃ 🧬 Mutant survived: calc/calc.go:8:8 → Comparison
┠┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
┃ --- calc/calc.go (original)
┃ +++ calc/calc.go (mutated with 'Comparison')
┃ @@ -5,7 +5,7 @@
┃  
┃  // Partly is exercised from one side only, so some of its mutants live.
┃  func Partly(a, b int) int {
┃ -	if a > b {
┃ +	if a >= b {
┃  		return a - b
┃  	}
┃  
┃ 
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╍┅
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ • Total:        7                    ┃
┃ • Killed:       4                    ┃
┃ • Survived:     3                    ┃
┠┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┨
┃ ✓ Score:     0.57 (minimum: 0.00)    ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Every survivor is listed by address before any diff is rendered, as path:line:col → Virus (what it replaced), so it can be jumped to rather than hunted for in the log.

More examples of the results can be found in the mutation.yml workflow.

Settings

Ditto's Release method takes variadic Options, like so:

ditto.Release(
	t,
	ditto.WithRepositoryRoot("."),
	ditto.WithTestCommand("make test"),
	ditto.WithMinimumThreshold(0.75),
	ditto.Parallel(),
	ditto.IgnoreSourceFiles("^release\\.go$"),
)

The table below presents all available options.

Viruses

Custom viruses

Ditto's viruses follow the viruses.Virus interface. All it takes to write a new virus is to have a struct that implements this interface. To get this new virus running, let Ditto know about it by running Release with the WithViruses(…) option. In order to test it, you may want to use the dittotesting package to help out. Take a look at the existing viruses to have an idea.

If your new virus is domain-agnostic, and you find it useful, consider contributing it to this project. You can also write domain-specific viruses. One that looks for a particular struct type and change it in a particular way, for example.

Tips

1. Ditto runs your test suite for every mutant it creates. Having a fast suite is a good idea. The way Ditto detects that a mutant was killed is by having a failing test. The quicker your suite catches the faster the mutation testing will finish. Go testing framework allows for us to flag it to fail fast with -failfast. Although this is better than nothing, this doesn't work across packages (see this issue for more details). This is where gotestsum comes in. It allows us to fail even faster by configuring it with --max-fails=1.
2. Mutation testing usually takes a significant amount of time to run. Especially if you have a large codebase. It may be a good approach to run it on a separate path on your CI pipeline; preferably after you get confirmation that your test suite is passing. This way you can get the results of the mutation testing without slowing down your main pipeline.
3. Ditto runs itself. I recommend exploring this codebase to get a better idea of how to use it.

Prior Art

Ditto is heavily inspired by go-mutesting, by @zimmski, and by extra mutations added to a fork by @avito-tech.

You can find more resources and tools on this subject by browsing through the mutation testing topic on GitHub. The awesome-mutation-testing repository also contains many good resources.

License

Ditto is open-source software released under the MIT License.