7 releases
0.1.5 | Jul 9, 2024 |
---|---|
0.1.4 | Jul 1, 2024 |
0.1.2-beta | Apr 11, 2024 |
#1023 in Parser implementations
497 downloads per month
185KB
4K
SLoC
Contains (JAR file, 61KB) gradle-wrapper.jar, (JAR file, 61KB) gradle-wrapper.jar
Mutant Kraken
A kotlin mutation testing tool built in Rust.
#################################################################################################################################
/$$ /$$ /$$ /$$ /$$ /$$ /$$
| $$$ /$$$ | $$ | $$ | $$ /$$/ | $$
| $$$$ /$$$$ /$$ /$$ /$$$$$$ /$$$$$$ /$$$$$$$ /$$$$$$ | $$ /$$/ /$$$$$$ /$$$$$$ | $$ /$$ /$$$$$$ /$$$$$$$
| $$ $$/$$ $$| $$ | $$|_ $$_/ |____ $$| $$__ $$|_ $$_/ | $$$$$/ /$$__ $$|____ $$| $$ /$$/ /$$__ $$| $$__ $$
| $$ $$$| $$| $$ | $$ | $$ /$$$$$$$| $$ \ $$ | $$ | $$ $$ | $$ \__/ /$$$$$$$| $$$$$$/ | $$$$$$$$| $$ \ $$
| $$\ $ | $$| $$ | $$ | $$ /$$ /$$__ $$| $$ | $$ | $$ /$$ | $$\ $$ | $$ /$$__ $$| $$_ $$ | $$_____/| $$ | $$
| $$ \/ | $$| $$$$$$/ | $$$$/| $$$$$$$| $$ | $$ | $$$$/ | $$ \ $$| $$ | $$$$$$$| $$ \ $$| $$$$$$$| $$ | $$
|__/ |__/ \______/ \___/ \_______/|__/ |__/ \___/ |__/ \__/|__/ \_______/|__/ \__/ \_______/|__/ |__/
#################################################################################################################################
Table of Contents
- Mutant Kraken
- Table of Contents
- Installation
- Usage
- How it works
- 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
- Contributing
- Notes
Installation
Mutant Kraken is currently in beta and is not ready for production use.
To install:
- 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)"
- Install the Mutant Kraken tap by running the following command in your terminal:
brew tap JosueMolinaMorales/mutant-kraken
- Install Mutant Kraken by running the following command in your terminal:
brew install mutant-kraken
- 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
ormutant-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:
- Gathering the files within the given directory
- Gathering mutations for each file
- Generating mutations for each file
- 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.
Dependencies
~46MB
~1M SLoC