Unleash

The main command used in Gremlins is unleash, that unleashes the gremlins and starts a mutation test of your code. If unleash is too long to type for you, you can use its aliases run and r.

Warning

At this time, this only works in the root of a Go module (where the go.mod file resides).

To execute a mutation testing run just type

gremlins unleash

If the module build requires tags

gremlins unleash --tags "tag1,tag2"

Flags

unleash supports several flags to fine tune its behaviour.

Dry run

--dry-run · Default: false

Just performs the analysis but not the mutation testing.

gremlins unleash --dry-run

Tags

--tags/-t · Default: empty

Sets the go command build tags.

gremlins unleash --tags "tag1,tag2"

Output

--output/-o · Default: empty

When set, Gremlins will write the give output file with machine readable results.

gremlins unleash --output=output.json

The output file in in JSON format and has the following structure:

{
  "go_module": "github.com/go-gremlins/gremlins",
  "test_efficacy": 82.00, //(1)
  "mutations_coverage": 80.00, //(2)
  "mutants_total": 100,
  "mutants_killed": 82,
  "mutants_lived": 8,
  "mutants_not_viable": 2, //(3)
  "mutants_not_covered": 10,
  "elapsed_time": 123.456, //(4)
  "files": [
    {
      "file_name": "myFile.go",
      "mutations": [
        {
          "line": 10,
          "column": 8,
          "type": "CONDITIONALS_NEGATION",
          "status": "KILLED"
        }
      ]
    }
  ]
}

1. This is a percentage expressed as floating point number.
2. This is a percentage expressed as floating point number.
3. NOT VIABLE mutants are excluded from all the calculations.
4. The elapsed time is expressed in seconds, expressed as floating point number.

Warning

The JSON output file is not pretty printed; it is optimised for machine reading.

Threshold efficacy

--threshold-efficacy · Default: 0

When set, it makes Gremlins exit with an error (code 10) if the test efficacy threshold is not met. By default it is zero, which means Gremlins never exits with an error.

The test efficacy is calculated as KILLED / (KILLED + LIVED) and assesses how effective are the tests.

gremlins unleash --threshold-efficacy 80

Threshold mutant coverage

--threshold-mcover · Default: 0

When set, it makes Gremlins exit with an error (code 11) if the mutant coverage threshold is not met. By default it is zero, which means Gremlins never exits with an error.

The mutant coverage is calculated as (KILLED + LIVED) / (KILLED + LIVED + NOT_COVERED) and assesses how many mutants are covered by tests.

gremlins unleash --threshold-mcover 80

Arithmetic base

--arithmetic-base · Default: true

Enables/disables the ARITHMETIC BASE mutant type.

gremlins unleash --arithmetic-base=false

Conditionals-boundary

--conditionals-boundary · Default: true

Enables/disables the CONDITIONALS BOUNDARY mutant type.

gremlins unleash --conditionals_boundary=false

Conditionals negation

--conditionals-negation · Default: true

Enables/disables the CONDITIONALS NEGATION mutant type.

gremlins unleash --conditionals_negation=false

Increment decrement

--increment-decrement · Default: true

Enables/disables the INCREMENT DECREMENT mutant type.

gremlins unleash --increment-decrement=false

Invert negatives

--invert-negatives · Default: true

Enables/disables the INVERT NEGATIVES mutant type.

gremlins unleash --invert_negatives=false