Mutant Kraken

A kotlin mutation testing tool built in Rust.

#################################################################################################################################

 /$$      /$$             /$$                           /$$           /$$   /$$                    /$$
| $$$    /$$$            | $$                          | $$          | $$  /$$/                   | $$
| $$$$  /$$$$ /$$   /$$ /$$$$$$    /$$$$$$  /$$$$$$$  /$$$$$$        | $$ /$$/   /$$$$$$  /$$$$$$ | $$   /$$  /$$$$$$  /$$$$$$$
| $$ $$/$$ $$| $$  | $$|_  $$_/   |____  $$| $$__  $$|_  $$_/        | $$$$$/   /$$__  $$|____  $$| $$  /$$/ /$$__  $$| $$__  $$
| $$  $$$| $$| $$  | $$  | $$      /$$$$$$$| $$  \ $$  | $$          | $$  $$  | $$  \__/ /$$$$$$$| $$$$$$/ | $$$$$$$$| $$  \ $$
| $$\  $ | $$| $$  | $$  | $$ /$$ /$$__  $$| $$  | $$  | $$ /$$      | $$\  $$ | $$      /$$__  $$| $$_  $$ | $$_____/| $$  | $$
| $$ \/  | $$|  $$$$$$/  |  $$$$/|  $$$$$$$| $$  | $$  |  $$$$/      | $$ \  $$| $$     |  $$$$$$$| $$ \  $$|  $$$$$$$| $$  | $$
|__/     |__/ \______/    \___/   \_______/|__/  |__/   \___/        |__/  \__/|__/      \_______/|__/  \__/ \_______/|__/  |__/

#################################################################################################################################

Table of Contents

• Mutant Kraken
  • Table of Contents
  • Installation
  • Usage
    • Commands
  • How it works
    • Gathering the files
    • Gathering Mutations
    • Generating Mutations
    • Running the tests
  • Operators
    • Arithmetic Replacement Operator
    • Unary Removal Operator
    • Logical Replacement Operator
    • Relational Replacement Operator
    • Assignment Replacement Operator
    • Unary Replacement Operator
    • Not Null Assertion Operator
    • Elvis Remove Operator
    • Elvis Litera Change Operator
    • Literal Change Operator
    • Exception Change Operator
    • When Remove Branch Operator
    • Remove Label Operator
    • Functional Binary Replacement Operator
    • Functional Replacement Operator
  • Configuration
    • General Configuration
      • timeout
      • operators
    • Ignore Configuration
      • ignore_files
      • ignore_directories
    • Threading Configuration
      • max_threads
    • Output Configuration
      • disable_end_table
    • Logging Configuration
      • log_level
    • Example JSON
  • Contributing
  • Notes

Installation

Mutant Kraken is currently in beta and is not ready for production use.

To install:

1. Ensure you have homebrew installed. If not, install it by running the following command in your terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install the Mutant Kraken tap by running the following command in your terminal:

brew tap JosueMolinaMorales/mutant-kraken

3. Install Mutant Kraken by running the following command in your terminal:

brew install mutant-kraken

4. Verify the installation by running the following command in your terminal:

mutant-kraken -v

You can also install Mutant-Kraken with the Rust toolchain:

cargo install mutant-kraken

This will install Mutant-Kraken in ~/.cargo/bin by default.

Usage

Mutant-Kraken is a mutation testing tool for Kotlin. It is currently in Beta. Please expect issues. If you come across any issues, please report them through the issues tab on the GitHub repository.

Commands

• mutant-kraken help or mutant-kraken -h: Prints the help menu.
• mutant-kraken mutate [PATH]: Runs the mutation testing tool on the path provided, or the current directory if no path is provided.
• mutant-kraken config: Displays information about how to setup the config file.
• mutant-kraken clean: Removes the mutant-kraken-dist directory

How it works

Mutant-Kraken has 5 stages:

1. Gathering the files within the given directory
2. Gathering mutations for each file
3. Generating mutations for each file
4. Running the tests for each mutation

Gathering the files

In this step, the tool looks at the given path and locates all potential Kotlin files to be mutated. It ignores any files that are not Kotlin files and follows the config that is provided.

If in the config you state that you do not want to mutate any files that end in Test.kt, then it will ignore any files that end in Test.kt. As well as ignoring any directories, for example the build directory

Example mk.config.json file that ignores all files that end in Test.kt and ignores the build directory:

"ignore": {
        "ignore_files": [
            "^.*Test\\.[^.]*$"
        ],
        "ignore_directories": [
            "build",
        ]
  }

Gathering Mutations

In this step, the tool looks at each file and gathers all the mutations that can be made for each file. It then stores the mutations in a file called mutations.json in the mutant-kraken-dist directory.

Generating Mutations

In this step, the tool generates all the mutation files and stores them in the mutant-kraken-dist/mutations directory.

Running the tests

In this step, the tool runs the tests for each mutation and stores the results in the mutant-kraken-dist/results directory.

Operators

Arithmetic Replacement Operator

Replaces an arithmetic operator with a different arithmetic operator

Unary Removal Operator

Removes a unary operator

Logical Replacement Operator

Replaces a logical operator with a different logical operator

Relational Replacement Operator

Replaces a relational operator with a different relational operator

Assignment Replacement Operator

Replaces an assignment operator with a different assignment operator

Unary Replacement Operator

Replaces a unary operator with a different unary operator

Not Null Assertion Operator

Replaces a not null assertion operator with a different not null assertion operator

Elvis Remove Operator

Removes an elvis operator

Elvis Litera Change Operator

Changes the literal of an elvis operator

Literal Change Operator

Changes the literal of a literal

Exception Change Operator

Changes the exception thrown

When Remove Branch Operator

Removes a branch from the when statement if the statement has more than one branch

Remove Label Operator

Removes a label when continuing, breaking, or returning

Functional Binary Replacement Operator

Changes first() to last() and vice versa or find() to findLast() and vice versa

Functional Replacement Operator

Changes Any() to All() or None() and vice versa or ForEach() to Map() or Filter() and vice versa

Configuration

Mutant-Kraken allows you to configure different aspects of the tool.

Here is a breakdown of what can be configured through the mutantkraken.config.json file:

General Configuration

This configuration is general to the tool.

timeout

Timeout expects a number and will stop the program after a certain amount of seconds pass

By default, timeout is not set

operators

Operators expects a list of the following string:

• ArithmeticReplacementOperator
• UnaryRemovalOperator
• LogicalReplacementOperator
• RelationalReplacementOperator
• AssignmentReplacementOperator
• UnaryReplacementOperator
• NotNullAssertionOperator
• ElvisRemoveOperator
• ElvisLiteralChangeOperator
• LiteralChangeOperator
• ExceptionChangeOperator
• WhenRemoveBranchOperator
• RemoveLabelOperator
• FunctionalBinaryReplacementOperator
• FunctionalReplacementOperator

By default all operators are enabled

Ignore Configuration

This configuration allows you to ignore files and directories using regex

ignore_files

Accepts a list of regex

By default it ignores all files that do not end in .kt

ignore_directories

Accepts a list of regex

By default it ignores all build directories

Threading Configuration

max_threads

The maxiumum amount of threads the tools is about to use

By default it is set to 30 threads

Output Configuration

This allows for configuration of the output displayed for the tool

disable_end_table

This expects a boolean where true means not to disable the end table

Defaults to false

Logging Configuration

Thi allows for configuration of the logging

log_level

This expects one of the following values:

• DEBUG
• INFO
• WARNING

Defaults to INFO

Example JSON

{
	"general": {
		"timeout": null,
		"operators": [
			"ArithmeticReplacementOperator",
			"AssignmentReplacementOperator"
		]
	},
	"ignore": {
		"ignore_files": ["^.*Test\\.[^.]*$"],
		"ignore_directories": ["dist", "build", "bin", ".gradle", ".idea", "gradle"]
	},
	"threading": { "max_threads": 30 },
	"output": { "display_end_table": false },
	"logging": { "log_level": "info" }
}

Contributing

If you would like to contribute to Mutant-Kraken, please read the CONTRIBUTING.md file.

Notes

• If you are working in a git repository, it is recommended to add the mutant-kraken-dist directory to your .gitignore file.