Cosmic Ray

Summary

Cosmic Ray is a free mutation-testing tool for Python 3 projects. It changes source code in small ways and runs a test suite for each change, checking whether the tests catch the altered behavior. This offers a different view from code coverage, which indicates whether a line ran. Cosmic Ray supports unittest, pytest, and nose. A TOML file specifies the modules to mutate, test command, timeout, exclusions, and distributor. The local distributor runs tests serially; the HTTP distributor sends work to local or remote workers for parallel execution, with each worker needing its own copy of the code. Reports are available through cr-report and cr-html, and users can add distributor or mutation-operator plugins. The tool changes code directly on disk, so its documentation recommends committing changes beforehand. Runs can take a long time because the suite is executed for each mutation, and the full configuration options are not currently well documented. Tests sharing a module with production code may also be mutated unless separated or excluded.

Who it is for

Cosmic Ray suits Python teams who want to check whether their tests detect behavioral changes, rather than relying only on line execution coverage. It is particularly relevant where teams can configure and run potentially lengthy test suites.

Compared on mutation testing tools

Free plan

Yescosmic-ray.readthedocs.io

Supported languages

Python 3cosmic-ray.readthedocs.io

Test frameworks

unittest, pytest, nosecosmic-ray.readthedocs.io

Incremental analysis

Yescosmic-ray.readthedocs.io

Parallel execution

Yescosmic-ray.readthedocs.io

Surviving mutant reports

Yescosmic-ray.readthedocs.io

Mutation operators

binary operator replacement; boolean replacement; break/continue replacement; comparison operator replacement; exception replacement; keyword replacement; number replacement; decorator removal; unary operator replacement; zero-iteration for loopscosmic-ray.readthedocs.io

Facts

Purpose

Cosmic Ray mutates Python source code and runs a test suite for each mutation to check whether the tests detect changed behavior.cosmic-ray.readthedocs.io · 3 Oct 2026

Install

The documentation recommends installing Cosmic Ray with `pip install cosmic-ray`.cosmic-ray.readthedocs.io · 3 Oct 2026

Test commands

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

Test runners

The documentation shows `unittest` and describes using `pytest` or `nose` with the `-x` option to stop after a failing test.cosmic-ray.readthedocs.io · 3 Oct 2026

Custom extensions

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

Reports

Cosmic Ray includes `cr-report` for session summaries and `cr-html` for generating an HTML report that shows the mutations used.cosmic-ray.readthedocs.io · 3 Oct 2026

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

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

Configuration limitation

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

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.github.com · 3 Oct 2026

Intended users

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

Testing value

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

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

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

Extensibility

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

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

Runtime limit

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

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

Maker

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

Where it ranks on Everything Xiaomi

• Best Mutation Testing Tools in 2026#8 of 25

Sources

• cosmic-ray.readthedocs.io/en/latest/· checked 3 Oct 2026
• cosmic-ray.readthedocs.io/en/latest/tutorials/intro/index.html· checked 3 Oct 2026
• cosmic-ray.readthedocs.io/en/latest/concepts.html· checked 3 Oct 2026
• github.com/sixty-north/cosmic-ray/blob/master/LICE· checked 3 Oct 2026
• cosmic-ray.readthedocs.io/en/stable/how-tos/filters.html· checked 4 Oct 2026