Cosmic Ray

8.4.6 verified Mon Apr 27 auth: no python

Cosmic Ray is a mutation testing tool for Python. It runs tests against mutated versions of your code to assess test suite quality. Current version 8.4.6. Release cadence is irregular with several minor releases per year.

pip install cosmic-ray

Common errors

error ModuleNotFoundError: No module named 'cosmic_ray' ↓

cause Package name on PyPI is 'cosmic-ray' (with a dash), but the import uses underscore.

fix

Install with pip: pip install cosmic-ray. Import with: import cosmic_ray.

error NameError: name 'main' is not defined ↓

cause The main entry point is in the cli submodule, not at the package root.

fix

Use from cosmic_ray.cli import main instead of from cosmic_ray import main.

Warnings

breaking In version 8.0.0, the CLI command structure changed from `cosmic-ray <subcommand>` to `cosmic-ray <subcommand> ...` with different argument order. Old scripts using positional arguments will break. ↓

fix Update to new CLI syntax: `cosmic-ray test --tests pytest --executor local my_module.py`

deprecated The `--baseline` option is deprecated in version 8.4.0 and may be removed in future versions. Use `--timeout` instead. ↓

fix Replace `--baseline` with `--timeout` (value in seconds).

gotcha Cosmic Ray requires an executor (local, celery, etc.). Default is not set; you must specify `--executor local` or configure one. ↓

fix Always include `--executor local` for local execution.

Imports

main

wrong

from cosmic_ray import main

correct

from cosmic_ray.cli import main

main is in the cli submodule, not top-level

Quickstart

Quickstart: Run cosmic-ray mutation testing on a module using pytest as the test runner.

from cosmic_ray.cli import main
import sys
# Run mutation test on a specific module
sys.argv = ['cosmic-ray', '--baseline=10', 'test', '--tests', 'pytest', '--executor', 'local', 'my_module.py']
main()