Cosmic Ray
cosmic-ray.readthedocs.io
- Free plan
- Linux
- Self-hosted
What Cosmic Ray is
Cosmic Ray is a free, MIT-licensed mutation-testing tool for Python 3 projects on Linux or self-hosted systems. It changes Python source code with mutation operators, then runs a configured test suite for each change to check whether tests detect altered behavior. This complements code coverage, which only indicates that a line ran. A TOML configuration defines modules, test command, timeout, exclusions, and the distributor. The documentation covers unittest and describes pytest or nose with the -x option. The local distributor runs work serially, while the HTTP distributor sends mutation and test requests to local or remote workers; each worker needs its own code copy. Users can add distributor and mutation-operator plugins. cr-report summarizes sessions, and cr-html creates an HTML report of mutations. Included filters can skip selected operators, marked lines, or unchanged lines relative to a Git branch. Cosmic Ray can also report surviving mutants.
Who it suits
It suits Python teams that want to check whether tests detect behavior changes, not just execute lines. It is aimed at projects able to manage local or distributed test runs and code copies.
Good to know, and what to watch
- Free plan and MIT license
- Supports unittest, pytest, and nose
- Local or remote parallel execution
- HTML and session reports
- Custom plugins and mutation filters
- Mutation runs can take hours
- Changes code directly on disk
- Configuration options are not fully documented
- Test modules may be mutated accidentally
The verdict
Cosmic Ray gives Python projects a configurable way to assess test effectiveness through mutation testing. Plan for long runtimes and protect the working tree before running it.
What the maker publishes
- Code handling
- Cosmic Ray applies mutations directly to code on disk, and the documentation advises committing changes first because a mutation might not be correctly undone after an exception or crash. source
- Configuration limitation
- The documentation says the full set of configuration options is not currently well documented. source
- Custom extensions
- Users can provide their own distributor and mutation operator plugins. source
- Execution modes
- The local distributor runs tests serially on the local machine, and the HTTP distributor sends work to local or remote workers that can run tests in parallel. source
- Extensibility
- Users can extend Cosmic Ray with their own mutation operators exposed through plugins. source
- Install
- The documentation recommends installing Cosmic Ray with `pip install cosmic-ray`. source
- Install
- The tutorial says to install Cosmic Ray with `pip install cosmic-ray`. source
- Intended users
- The documentation presents Cosmic Ray for Python projects whose teams want to check whether their test suites meaningfully verify code behavior. source
- License
- The project repository identifies the software as MIT licensed, with permission to use, copy, modify, distribute, and sell copies subject to the license conditions. source
- License
- The project repository identifies the software as MIT licensed. source
- Maker
- The project documentation credits Sixty North AS. source
- Mutation filters
- Included filters can skip mutations by operator name, a `# pragma: no mutate` comment, or whether the mutated line changed relative to a Git branch. source
- Notable limitation
- Cosmic Ray may mutate test code if it shares a module with the production code under test; the documentation recommends keeping tests separate or excluding their modules. source
- Parallel execution
- The HTTP distributor sends mutation and test requests to workers that can run locally or remotely; each worker needs its own copy of the code under test. source
- Purpose
- Cosmic Ray mutates Python source code and runs a test suite for each mutation to check whether the tests detect changed behavior. source
- Purpose
- Cosmic Ray is a mutation testing tool for Python 3 that makes small changes to production code and runs the test suite against each change. source
- Reports
- Cosmic Ray includes `cr-report` for session summaries and `cr-html` for generating an HTML report that shows the mutations used. source
- Reports
- Cosmic Ray provides `cr-report` for session summaries and `cr-html` for generating an HTML report that shows the mutation used. source
- Runtime consideration
- Mutation testing can take a long time because the tool runs the test suite for each mutation; the documentation gives an example where 1,000 mutations and a 10-second test suite take about 2.7 hours. source
- Runtime limit
- A configured timeout ends a mutant test that runs too long, and Cosmic Ray marks that mutant incompetent. source
- Target users
- The documentation describes Cosmic Ray as a tool for Python projects and says it has been used on projects ranging from assemblers to oil exploration software. source
- Test commands
- A TOML configuration specifies the modules to mutate, test command, timeout, exclusions, and distributor. source
- Testing value
- Mutation testing checks whether tests detect changes in behavior, while code coverage indicates whether a line was executed. source
- Test runners
- The documentation shows `unittest` and describes using `pytest` or `nose` with the `-x` option to stop after a failing test. source
Checked against the maker's pages on 4 Oct 2026.