Cosmic Ray

Spec sheet

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.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

Intended users

The documentation presents Cosmic Ray for Python projects whose teams want to check whether their test suites meaningfully verify code behavior.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

License

The project repository identifies the software as MIT licensed.Read 4 Oct 2026 · github.com

Maker

The project documentation credits Sixty North AS.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

Configuration limitation

The documentation says the full set of configuration options is not currently well documented.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

Custom extensions

Users can provide their own distributor and mutation operator plugins.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

Extensibility

Users can extend Cosmic Ray with their own mutation operators exposed through plugins.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

Install

The tutorial says to install Cosmic Ray with `pip install cosmic-ray`.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

Reports

Cosmic Ray provides `cr-report` for session summaries and `cr-html` for generating an HTML report that shows the mutation used.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

Runtime limit

A configured timeout ends a mutant test that runs too long, and Cosmic Ray marks that mutant incompetent.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

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.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

Test commands

A TOML configuration specifies the modules to mutate, test command, timeout, exclusions, and distributor.Read 3 Oct 2026 · cosmic-ray.readthedocs.io

Test runners

The documentation shows test commands using `unittest` and says `pytest` and `nose` can stop after a failing test with the `-x` option.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

Testing value

Mutation testing checks whether tests detect changes in behavior, while code coverage indicates whether a line was executed.Read 4 Oct 2026 · cosmic-ray.readthedocs.io

Where Specifiction places it

• Mutation Testing Tools#13 of 257.5