README.md

jmutator

This is a tool to mutate Java bytecode (.class files). The input is a folder with .class files, and the tool will produce several mutations (.class files) for each. The names of the mutated class files can be specified using a simple template language. See examples in tests for details.

For each mutated .class file, a provenance file in JSON format is created that describes the mutations made. pitest is used as mutation engine. This should always result in valid bytecode, but the tool also has the option to run additional bytecode verification based on ASM as described here.

Requirements

Java 11 or better and Maven 3.9 or better (earlier versions of Maven might also work)

Building

mvn package , this will generate the executable target/jmutator.jar.

Usage

usage: java -jar jmutator.jar
 -b,--binaries folder <arg>           root folder containing .class files
 -j,--provenance pattern <arg>        a pattern used to name json-encoded
                                      provenance files, must contain the
                                      strings $n (the original class file
                                      name without extension) and $i (the
                                      mutation number, and int))
 -m,--mutated binaries folder <arg>   folder to write the mutated  .class
                                      files to
 -p,--conversion pattern <arg>        a pattern used to name mutated class
                                      files, must contain the strings $n
                                      (the original class file name
                                      without extension) and $i (the
                                      mutation number, and int))
 -v,--verify                          verify generated byte code
                                      (verification is ASM-based, will
                                      result in error if verification
                                      fails)

Provenance

This is an example of a mutation provenance file that is being generated for each mutated .class file:

{
    "description": "negated conditional",
    "location": {
        "line": 6,
        "method-descriptor": "(I)Z",
        "method-name": "isEvenNumber",
        "class": "com.foo.PrimeNumberChecker"
    },
    "mutator": "org.pitest.mutationtest.engine.gregor.mutators.NegateConditionalsMutator"
}