Plugin API

A plugin is a jar built against these types. Depend on them for compiling only: mutastic provides them when it loads the plugin. This reference is written from the API's own doc comments.

io.mutastic.api

In io.mutastic:mutastic-api.

BuildTool	interface	A build tool mutastic reads a project’s setup from, found with java.util.ServiceLoader: each is asked in turn whether a directory is one of its builds.
BuildTool.Request	record	What to read: a module of the build in directory, and which of its test suites.
BuildTool.SetupFailed	class	The build couldn’t be read: the message says what to do instead.
BuiltIn	enum	mutastic’s own operators.
ChangedLines	record	The source lines a change touched, by file: what a run scoped to a change mutates.
Comparison	record	This run against the last one.
Comparison.Flip	record	A mutant caught in one run and not the other.
CoveragePass	record	What the coverage pass found, before any mutant runs.
Filter	interface	Decides that a method’s mutants shouldn’t run, and says why.
FlakyTest	record	What a flaky test’s failure and reach say about why it’s flaky: the difference between a test that’s its own doing (an unseeded Random, the clock), which can be made to give the same answer every time, and one that reaches outside the code (the network, a database), where changing the test or the code to get past it would hide what’s wrong.
Ignore	record	A mutant the project has decided not to test, by id, from .mutastic/ignores.yaml: written by mutastic ignore, committed, and reviewed like code.
Listener	interface	Hears about a run as it happens, for progress and streamed output.
Mutant	record	One mutation of one instruction: which method, which mutation site in it (counted in bytecode order), and what the instruction becomes.
MutantResult	record	One mutant’s outcome.
Mutator	interface	An operator a plugin adds, or a rules file describes: which instructions it changes, how, and what a missed mutant’s card says.
Mutator.Change	record	One change at a site.
Mutator.Site	record	One instruction, with the code around it.
Mutator.Words	record	A missed mutant’s card, in words.
Operator	interface	A kind of change mutastic makes: one of its own (BuiltIn), or one a plugin or rules file adds (Mutator).
Operator.Tier	enum	The sets operators come in.
Policy	record	A project’s own say over which mutants run: the mutants it ignores by id (from .mutastic/ignores.yaml), and from mutastic.yaml its rules, then filters of its own (found in its plugins, run only when named), after the built-in ones; which operators run, and the operators its plugins and rules files add.
Project	record	One module’s code and tests, and how its build runs them: what a build-tool integration reads from the module’s test task.
ProjectSetup	class	The setup file a build tool’s own code writes from inside the build (Gradle’s init script, Maven’s extension): a properties file with what the module’s tests run with.
Report	record	A finished run: every mutant’s result, in the order they were found.
Rule	record	A project’s own decision, from mutastic.yaml: skip the mutants in some code, or mutate code a built-in filter would skip as arid, with the reason.
Skip	record	Why a mutant doesn’t run.
Skip.Kind	enum	What the skip claims: GENERATED, EQUIVALENT and UNVIABLE are facts about the bytecode (an unviable change wouldn’t load); ARID is a judgement that the mutant isn’t worth a test; USER is the project’s own decision.
Status	enum	What happened to a mutant.
Suggestion	record	A call that tells a missed mutant from the code today, found by running both: the test to write is an assertion of today’s value.
Suggestion.Instance	record	An instance a suggestion makes: its class’s simple name and constructor arguments, Window and [5, 10].
TestSelection	record	Which of a module’s tests its build runs: the test task’s or Surefire’s patterns and JUnit tags.

io.mutastic.annotations

In io.mutastic:mutastic-annotations.

Annotations for code mutastic tests: DoNotMutate to skip, DoMutate to keep what would be skipped. Read from the class files, so they cost nothing at run time.

DoMutate	annotation	mutastic mutates this method, or every method of this class, even where it would skip it as arid: a toString() that customers see, a getter that is a contract.
DoNotMutate	annotation	mutastic skips the mutants in this method, or in every method of this class, and reports them as skipped with value as the reason: @DoNotMutate("measured by the load tests").