go-mutesting

You can use special comment annotations directly in your Go source code to provide granular control over which parts of the code are mutated. These annotations only apply to the file where they are declared.

Supported Annotations

1. // mutator-disable-func: Disables all mutations for the function immediately following the comment.
2. // mutator-disable-next-line <mutator1>, <mutator2>: Disables specific mutators (or * for all) for the next line.
3. // mutator-disable-regexp <pattern> <mutator1>, <mutator2>: Disables mutations for any line matching the provided regex pattern.

// mutator-disable-func  
func CalculateDiscount(price float64) float64 {  
    return price * 0.9  
} 

// mutator-disable-next-line *  
x = 42  // Fully protected

// mutator-disable-next-line branch/if, increment  
if x > 0 {  // Only branch/if and increment mutators are disabled
    y += 1  
}

// mutator-disable-regexp s\.Method\(\) *  
s.Method()

To run mutation testing, provide targets such as Go source files, directories, or packages. You can use the ... wildcard for recursive searching. Note that files ending in _test are automatically excluded.

By default, go-mutesting uses a built-in execution command that replaces the original file with the mutation, runs the package tests, and reports if the mutation was killed.

To use a custom execution command, use the --exec flag. This is useful if you need specific testing logic or want to use the provided scripts in the /scripts/exec directory.

# Run mutation testing on specific files, directories, and packages
go-mutesting parse.go example/ github.com/avito-tech/go-mutesting/mutator/...

# Run mutation testing using a custom exec command
go-mutesting --exec "$GOPATH/src/github.com/avito-tech/go-mutesting/scripts/exec/test-mutated-package.sh" github.com/avito-tech/go-mutesting/example

The go-mutesting command performs mutation testing on Go source code by injecting faults (mutants) into the code and running tests to see if they catch the changes.

Basic usage involves passing target files or packages as arguments. The tool will identify suitable Go files, apply mutators, execute tests, and generate a report.

Common workflows:

• List available mutators: Use the --list-mutators flag to see which mutation types are implemented.
• List target files: Use the --list-files flag to see which files the tool has identified as targets.
• Print AST: Use the --print-ast flag to inspect the Abstract Syntax Tree of the target files.
• Filter by function: Use the --filter-match <regex> flag to only mutate functions whose names match the provided regular expression.

# Example: Run mutation testing on a specific file
go-mutesting ./path/to/your/file.go

# Example: List all implemented mutators
go-mutesting --list-mutators

# Example: Mutate only functions matching a regex
go-mutesting --filter-match "^Test.*" ./pkg/...

A mutation exec command is a script or binary invoked for every mutation to determine if it was 'killed'. It must be stateless and isolated.

Required Workflow

1. Setup: Apply the mutation to the source.
2. Test: Run the test suite.
3. Cleanup: Revert changes and remove temporary files.
4. Report: Exit with a specific code indicating the result.

Environment Variables

go-mutesting passes the following variables to your command:

• MUTATE_CHANGED: Filename of the mutated file.
• MUTATE_DEBUG: Enable debugging output.
• MUTATE_ORIGINAL: Filename of the original file.
• MUTATE_PACKAGE: Import path of the original file.
• MUTATE_TIMEOUT: Timeout for the execution.
• MUTATE_VERBOSE: Enable verbose output.
• TEST_RECURSIVE: Whether to run tests recursively.

Exit Codes

Below is a detailed list of the mutators implemented in go-mutesting.

Arithmetic Mutators

arithmetic/base

arithmetic/bitwise

arithmetic/assign_invert

arithmetic/assignment

Loop Mutators

loop/break

loop/condition

loop/range_break

Adds a break to the beginning of each range loop.

Numbers Mutators

numbers/incrementer

numbers/decrementer

Conditional Mutators

conditional/negated

Branch Mutators

branch/case

Empties case bodies.

branch/if

Empties branches of if and else if statements.

branch/else

Empties branches of else statements.

Expression Mutators

expression/comparison

Replaces comparison operators with similar operators to catch off-by-one errors.

expression/remove

Replaces && and || operators by making each term irrelevant using true or false.

Statement Mutators

statement/remove

Removes assignment, increment, decrement, and expression statements.