Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

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.