mutastic run

Mutate the code and run its tests against each mutant. DIR is the build, here unless given, and :MODULE one of its modules: as Gradle names it (:app), or as Maven's -pl takes it (:services/api). The run passes when the score reaches the threshold. A full run writes report files, keeps a record the next run compares with, and offers the commands to work on each missed mutant.

Usage

mutastic run [DIR] [:MODULE] [OPTIONS]

The build plugins run the same command, with each option as a mutastic. property of the same name.

./gradlew mutasticRun
./gradlew mutasticRun \
  -Pmutastic.threshold=70 \
  -p samples/pricing
./gradlew mutasticRun \
  -Pmutastic.since=main
./gradlew :core:mutasticRun \
  -Pmutastic.testsFrom=dependents

mvn mutastic:run
mvn mutastic:run \
  -Dmutastic.threshold=70 \
  -f samples/pricing
mvn mutastic:run \
  -Dmutastic.since=main
mvn mutastic:run \
  -Dmutastic.testsFrom=dependents \
  -pl core

mutastic run
mutastic run \
  samples/pricing \
  --threshold=70
mutastic run --since=main
mutastic run \
  . \
  :core \
  --tests-from=dependents

Options

`--threshold=N`

The score a run must reach, from 0 to 100; 80 unless set.

Gradle	`-Pmutastic.threshold=N` or `threshold = …` in `mutastic { }`
Maven	`-Dmutastic.threshold=N` or `<threshold>…</threshold>` in the plugin's configuration
Command line	`--threshold=N`

./gradlew mutasticRun \
  -Pmutastic.threshold=70

mutastic {
    threshold = 70
}

mvn mutastic:run \
  -Dmutastic.threshold=70

<configuration>
  <threshold>70</threshold>
</configuration>

mutastic run --threshold=70

`--since[=REF]`

Mutate only the lines changed since REF; the default branch without one.

Gradle	`-Pmutastic.since=REF` or `since = …` in `mutastic { }`
Maven	`-Dmutastic.since=REF` or `<since>…</since>` in the plugin's configuration
Command line	`--since[=REF]`

./gradlew mutasticRun \
  -Pmutastic.since=main

mutastic {
    since = "main"
}

mvn mutastic:run \
  -Dmutastic.since=main

<configuration>
  <since>main</since>
</configuration>

mutastic run --since=main

`--only=ID`

Run one mutant; the run passes when it's caught.

Gradle	`-Pmutastic.only=ID`
Maven	`-Dmutastic.only=ID`
Command line	`--only=ID`

`--tests-from=MODULE`

Also run this module's tests over what this one's miss: :app, or dependents for every module that depends on it.

Gradle	`-Pmutastic.testsFrom=MODULE,…` or `testsFrom = …` in `mutastic { }`
Maven	`-Dmutastic.testsFrom=MODULE,…` or `<testsFrom>…</testsFrom>` in the plugin's configuration
Command line	`--tests-from=MODULE`

./gradlew :core:mutasticRun \
  -Pmutastic.testsFrom=dependents

mutastic {
    testsFrom = listOf("dependents")
}

mvn mutastic:run \
  -Dmutastic.testsFrom=dependents \
  -pl core

<configuration>
  <testsFrom>
    <module>dependents</module>
  </testsFrom>
</configuration>

mutastic run \
  . \
  :core \
  --tests-from=dependents

`--workers=N`

How many workers run side by side; half the cores, from 1 to 4, unless set.

Gradle	`-Pmutastic.workers=N` or `workers = …` in `mutastic { }`
Maven	`-Dmutastic.workers=N` or `<workers>…</workers>` in the plugin's configuration
Command line	`--workers=N`

./gradlew mutasticRun \
  -Pmutastic.workers=2

mutastic {
    workers = 2
}

mvn mutastic:run \
  -Dmutastic.workers=2

<configuration>
  <workers>2</workers>
</configuration>

mutastic run --workers=2

`--confirm-catches`

Run each catching test again on its own, to confirm the catch.

Gradle	`-Pmutastic.confirmCatches` or `confirmCatches = true` in `mutastic { }`
Maven	`-Dmutastic.confirmCatches` or `<confirmCatches>true</confirmCatches>` in the plugin's configuration
Command line	`--confirm-catches`

./gradlew mutasticRun \
  -Pmutastic.confirmCatches

mutastic {
    confirmCatches = true
}

mvn mutastic:run \
  -Dmutastic.confirmCatches

<configuration>
  <confirmCatches>true</confirmCatches>
</configuration>

mutastic run --confirm-catches

`--no-suggestions`

Don't look for a test to suggest for each missed mutant.

Gradle	`-Pmutastic.suggestions=false` or `suggestions = false` in `mutastic { }`
Maven	`-Dmutastic.suggestions=false` or `<suggestions>false</suggestions>` in the plugin's configuration
Command line	`--no-suggestions`

./gradlew mutasticRun \
  -Pmutastic.suggestions=false

mutastic {
    suggestions = false
}

mvn mutastic:run \
  -Dmutastic.suggestions=false

<configuration>
  <suggestions>false</suggestions>
</configuration>

mutastic run --no-suggestions

`--report=KIND[:PATH]`

A report file a full run writes: json, html or xml, or none; json and html unless set.

Gradle	`-Pmutastic.reports=KIND[:PATH],…` or `reports = …` in `mutastic { }`
Maven	`-Dmutastic.reports=KIND[:PATH],…` or `<reports>…</reports>` in the plugin's configuration
Command line	`--report=KIND[:PATH]`

./gradlew mutasticRun \
  -Pmutastic.reports=xml

mutastic {
    reports = listOf("xml")
}

mvn mutastic:run \
  -Dmutastic.reports=xml

<configuration>
  <reports>
    <report>xml</report>
  </reports>
</configuration>

mutastic run --report=xml

`--format=FORMAT`

How the result is shown; full on a terminal, concise elsewhere, agent for coding agents.

One of fullbriefconcisegroupedagentjsonl

Gradle	`-Pmutastic.format=FORMAT` or `format = …` in `mutastic { }`
Maven	`-Dmutastic.format=FORMAT` or `<format>…</format>` in the plugin's configuration
Command line	`--format=FORMAT`
Environment	`MUTASTIC_FORMAT, MUTASTIC_AGENT`

./gradlew mutasticRun \
  -Pmutastic.format=agent

mutastic {
    format = "agent"
}

mvn mutastic:run \
  -Dmutastic.format=agent

<configuration>
  <format>agent</format>
</configuration>

mutastic run --format=agent

`--vocabulary=WORDS`

plain says caught and missed; classic says killed and survived.

One of plainclassic

Gradle	`-Pmutastic.vocabulary=WORDS`
Maven	`-Dmutastic.vocabulary=WORDS`
Command line	`--vocabulary=WORDS`
Environment	`MUTASTIC_VOCABULARY`

./gradlew mutasticRun \
  -Pmutastic.vocabulary=classic

mvn mutastic:run \
  -Dmutastic.vocabulary=classic

mutastic run --vocabulary=classic

`--color=WHEN`

Colour: auto uses it on a terminal that wants it.

One of autoalwaysnever

Gradle	`-Pmutastic.color=WHEN`
Maven	`-Dmutastic.color=WHEN`
Command line	`--color=WHEN`
Environment	`NO_COLOR, FORCE_COLOR`

`--hyperlinks=WHEN`

File locations as links a terminal can open: auto uses them on a terminal.

One of autoalwaysnever

Gradle	`-Pmutastic.hyperlinks=WHEN`
Maven	`-Dmutastic.hyperlinks=WHEN`
Command line	`--hyperlinks=WHEN`

`--progress=STYLE`

Progress on stderr: a bar on a terminal, counter lines in logs, none for agents.

One of autobarcounternone

Gradle	`-Pmutastic.progress=STYLE`
Maven	`-Dmutastic.progress=STYLE`
Command line	`--progress=STYLE`