https://github.com/sivchari/gomu
🚀 High-performance mutation testing tool for Go
https://github.com/sivchari/gomu
go golang mutation-testing
Last synced: 15 days ago
JSON representation
🚀 High-performance mutation testing tool for Go
- Host: GitHub
- URL: https://github.com/sivchari/gomu
- Owner: sivchari
- License: mit
- Created: 2025-07-14T03:09:29.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-15T09:12:01.000Z (8 months ago)
- Last Synced: 2025-08-15T09:18:53.694Z (8 months ago)
- Topics: go, golang, mutation-testing
- Language: Go
- Homepage:
- Size: 3.29 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gomu
A high-performance mutation testing tool for Go that helps validate the quality of your test suite.
[](https://golang.org/dl/)
[](https://opensource.org/licenses/MIT)
## What is Mutation Testing?
Mutation testing evaluates the quality of your test suite by introducing controlled changes (mutations) to your code and checking if your tests catch them. If a test fails when code is mutated, the mutation is "killed" (good). If tests still pass, the mutation "survived" (indicates weak tests).
## Features
### High Performance
- **Incremental Analysis**: Only test changed files with Git integration
- **Parallel Execution**: Leverage goroutines for concurrent mutation testing
- **Efficient AST Processing**: Fast Go code analysis and mutation generation
### Go-Specific Optimizations
- **Type-Safe Mutations**: Leverage Go's type system for intelligent mutations
- **Error Handling Patterns**: Specialized mutations for Go error handling
- **Interface Mutations**: Targeted interface implementation testing
### CI/CD Integration
- **Quality Gates**: Configurable mutation score thresholds
- **GitHub Integration**: Automatic PR comments with test results
- **Multiple Output Formats**: JSON, HTML, and console reporting
- **Artifact Generation**: CI-friendly report artifacts
### Developer Experience
- **CLI-Based Configuration**: Simple command-line flags for all settings
- **Rich Reporting**: Detailed HTML, JSON, and console output formats
- **Flexible Targeting**: Run on specific files, directories, or changed files only
- **.gomuignore Support**: Exclude files and directories from mutation testing
### Advanced Analysis
- **History Tracking**: JSON-based incremental analysis for faster reruns
- **Git Integration**: Automatic detection of changed files
- **Mutation Score**: Comprehensive quality metrics
- **Detailed Reports**: Line-by-line mutation analysis
## Installation
```bash
go install github.com/sivchari/gomu/cmd/gomu@latest
```
Or clone and build:
```bash
git clone https://github.com/sivchari/gomu.git
cd gomu
go build -o gomu ./cmd/gomu
```
## Quick Start
1. **Run on current directory:**
```bash
gomu run
```
2. **Run in CI environment:**
```bash
gomu run --ci-mode
```
3. **Run on specific directory:**
```bash
gomu run ./pkg/mypackage
```
4. **Verbose output:**
```bash
gomu run -v
```
5. **Custom threshold and workers:**
```bash
gomu run --threshold 85.0 --workers 8
```
## Commands
### Basic Usage
- `gomu run [path]` - Run mutation testing on the specified path (default: current directory)
- `gomu version` - Show version information
### Run Command Options
| Flag | Default | Description |
|------|---------|-------------|
| `--ci-mode` | `false` | Enable CI mode with quality gates and GitHub integration |
| `--threshold` | `80.0` | Minimum mutation score threshold (0-100) |
| `--workers` | `4` | Number of parallel workers |
| `--timeout` | `30` | Test timeout in seconds |
| `--incremental` | `true` | Enable incremental analysis |
| `--base-branch` | `main` | Base branch for incremental analysis |
| `--output` | `console` | Output format (console, json, html, text) |
| `--fail-on-gate` | `true` | Fail build when quality gate is not met |
| `-v, --verbose` | `false` | Verbose output |
### Examples
```bash
# Basic run with default settings
gomu run
# Run with custom threshold
gomu run --threshold 85.0
# Run in CI mode with HTML output
gomu run --ci-mode --output html
# Run with more workers and longer timeout
gomu run --workers 8 --timeout 60
# Run on specific package with verbose output
gomu run ./internal/mypackage -v
# Disable incremental analysis
gomu run --incremental=false
```
## .gomuignore
Create a `.gomuignore` file in your project root to exclude files and directories from mutation testing. The syntax is similar to `.gitignore`:
```
# Exclude directories
cmd/
vendor/
testdata/
# Exclude specific files
*_generated.go
# Negate pattern (include previously excluded)
!cmd/important/
```
## Mutation Types
### Arithmetic Mutations
- Replace `+` with `-`, `*`, `/`
- Replace `-` with `+`, `*`, `/`
- Replace `*` with `+`, `-`, `/`, `%`
- Replace `/` with `+`, `-`, `*`, `%`
- Replace `++` with `--` and vice versa
### Conditional Mutations
- Replace `==` with `!=`, `<`, `<=`, `>`, `>=`
- Replace `!=` with `==`, `<`, `<=`, `>`, `>=`
- Replace `<` with `<=`, `>`, `>=`, `==`, `!=`
- Replace `>` with `>=`, `<`, `<=`, `==`, `!=`
### Logical Mutations
- Replace `&&` with `||`
- Replace `||` with `&&`
- Remove `!` (NOT) operators
### Bitwise Mutations
- Replace `&` with `|`, `^`
- Replace `|` with `&`, `^`
- Replace `^` with `&`, `|`
- Replace `>>` with `<<`
- Replace `<<` with `>>`
## CI/CD Integration
### GitHub Actions
```yaml
name: Mutation Testing
on:
pull_request:
branches: [main]
jobs:
mutation-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.21'
- name: Install gomu
run: go install github.com/sivchari/gomu/cmd/gomu@latest
- name: Run mutation testing
run: gomu run --ci-mode --threshold 80.0
- name: Upload mutation report
uses: actions/upload-artifact@v4
if: always()
with:
name: mutation-report
path: |
mutation-report.html
mutation-report.json
```
### Quality Gates
Quality gates automatically fail the build when mutation score falls below threshold:
- Configurable minimum mutation score via `--threshold`
- Fail or continue build via `--fail-on-gate`
- Detailed failure reporting in CI output
## Example Output
### Console Output
```
Running mutation testing with the following settings:
Path: .
CI Mode: true
Workers: 4
Timeout: 30 seconds
Output: json
Incremental: true
Base Branch: main
Threshold: 80.0%
Fail on Gate: true
Analyzing files for changes...
Incremental Analysis Report
==========================
- src/calculator.go - File content changed
- src/utils.go - No previous history
Summary: 2 files need testing, 3 files skipped
Performance improvement: 60.0% files skipped
Running mutation testing on 2 files...
Quality Gate: PASSED (Score: 84.4%)
Mutation testing completed successfully
```
### HTML Report
The HTML report provides:
- Interactive mutation score dashboard
- File-by-file mutation breakdown
- Survived mutant details with code snippets
- Quality gate status and recommendations
## Incremental Analysis
gomu features PITest-inspired incremental analysis that dramatically speeds up repeated runs:
1. **File Hashing**: Tracks changes to source files and tests
2. **Git Integration**: Automatically detects changed files since last commit
3. **Result Caching**: Reuses previous results for unchanged code
4. **JSON Storage**: Transparent, debuggable history format (`.gomu_history.json`)
This can reduce execution time from minutes to seconds on large codebases.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by [PITest](https://pitest.org/) for Java
- Builds upon research in mutation testing
- Thanks to the Go community for excellent tooling