Skip to main content

gdmutant: banner with Frank the Mutant, the project mascot

Mutation testing for GDScript and Godot: find the bugs your green tests would miss.

CI PyPI Godot 4.3+ GUT 9.x gdUnit4 6.x Python 3.12+ License: MIT

A community tool, not affiliated with or endorsed by the Godot Foundation.

What it is

Coverage tells you a line ran. Mutations tell you if a bug there would be caught: a killed mutant means yes, a survivor means no. A standalone CLI, no AI required. You can use it to check whether AI-generated tests catch deliberately introduced bugs.

Same idea, other languages: mutmut for Python, Stryker for JS/TS, PIT for Java.

gdmutant mutates your GDScript (flips >↔>=, and↔or, bumps a number, deletes a statement), reruns your tests once per change, and reports the survivors.

The --html report, open on turn_order.gd. A survivor in the source, and marked on line 27:

turn_order.gd:27, return alive and not stunned, with and marked as a survivor

and its detail card: what it means, why it's risky, and how to close it.

The detail card: survived, boolean, turn_order.gd:27, func can_act. Gap: tests pass whether this needs both sides or just one. Risk: a change that loosens or tightens the guard would pass every test. Start: add a test where exactly one side is true and the other false, and assert the outcome

Prerequisites

  • Godot 4.3+ (see Compatibility for exact versions), on your PATH so a plain godot --version works, or pass --godot <full-path> on every gdmutant command instead.
  • GUT or gdUnit4, already installed and enabled in your project, if you use either. A different test runner works too, via --runner command: any headless command that exits non-zero on failure.
  • Python 3.12+ (check with python --version).
  • A test suite that already passes. gdmutant reruns your tests once per mutant and reports the ones they miss, so it needs a green baseline to compare against, not a red one.

Quickstart

This mutates corpus/, a small real Godot project bundled in this repo just for this: a real script and a real GUT/gdUnit4 suite to try gdmutant against before pointing it at your own.

git clone https://github.com/kphutt/gdmutant   # for corpus/, the sample project you'll mutate

cd gdmutant                                # corpus/ lives right here, at the repo root

pip install 'gdmutant==0.1.*'              # the released CLI, from PyPI (0.x: pin the minor)

gdmutant run corpus/turn_order.gd --dry-run
# preview: lists the mutants gdmutant would try. No Godot needed, no test run, no survivors yet.

That's a preview, not the payoff: --dry-run only lists mutants, it never runs a test against them. The actual point of gdmutant is the survivor: a mutant whose test run still passed, meaning it marks a line where a real bug could hide and nothing would catch it. Seeing one for real means rerunning corpus/'s actual GUT/gdUnit4 suite:

python scripts/install_gdunit4.py          # gdUnit4 is a Godot addon that isn't vendored in git. This fetches it

# The first run below goes quiet for a bit right after it starts: that's Godot importing every
# asset in the project, a one-time cost, not a hang.
gdmutant run corpus/turn_order.gd --project corpus --runner gdunit4 --html
# mutates one file, reruns corpus/'s real GdUnit4 tests against each mutant

Output:

...

  corpus/turn_order.gd:27   func can_act

     27 |     return alive and not stunned
        |                  ^  changed  and  to  or: every test still passed

  gap    Your tests pass whether this needs both sides (`and`) or just one
         (`or`). No test covers the case that tells them apart: the
         operands disagreeing (one true, one false).

  risk   Your tests can't tell 'needs both' from 'needs either.' A change
         that loosens or tightens this guard would pass every test.

  start  Add a test where exactly one side is true and the other false,
         and assert the outcome.

  more   https://github.com/kphutt/gdmutant/blob/main/docs/survivors/README.md#boolean
──────────────────────────────────────────────────────────────────────────

Results

Mutation score: 61.1%
  killed:   11
  timeout:  0  (counted as killed)
  survived: 7
  ignored:  0  (suppressed, excluded from score)
  invalid:  0
  error:    0

Wrote HTML report to gdmutant-report-turn_order-<timestamp>.html. Open it in a browser.

Point it at your own project

pip install 'gdmutant==0.1.*'   # gdmutant is 0.x: pin the minor so a new one is a move you make on purpose

Pick your test runner with --runner (required): GUT or gdUnit4. Godot has no built-in test runner, so both ship as addons: a plugin folder (addons/gut/ or addons/gdUnit4/) that lives inside a Godot project. Whichever you pick needs to already be installed there, in the project you're pointing gdmutant at. Godot itself needs to be on PATH, or point at it with --godot <path>. gdUnit4's usual test layout matches gdmutant's default --tests res://test, so a gdUnit4 command needs no --tests flag. GUT needs it spelled out: its stock layout puts suites in test/unit/ instead, and GUT's own -gdir doesn't search subdirectories.

# GUT
gdmutant run ../my-project/src/module.gd --project ../my-project --runner gut --tests res://test/unit --json
# gdUnit4
gdmutant run ../my-project/src/module.gd --project ../my-project --runner gdunit4 --json

Typing those flags every run gets old. gdmutant init writes a starter .gdmutant.toml in the current directory so you don't have to. It sets tests to the usual default and, if it finds a gdUnit4 or GUT addon already installed, sets runner to match. Every other setting is listed as a commented example. It won't overwrite a config you already have unless you pass --force.

gdmutant init                   # writes .gdmutant.toml, then edit it and drop the flags

On a project big enough for the run to take a while, --jobs auto picks a worker count for you instead of making you choose. It uses the machine's processor count as a ceiling, and on Linux and macOS it also watches the load average (a rolling measure of how busy the machine is) and waits up to 30 seconds before starting each extra worker while that is high, so a long run shares the machine rather than taking it over. After 30 seconds it starts the worker anyway. Windows has no load average, so there it just uses the ceiling.

--json follows the mutation-testing-elements schema

See the survivor reference for what ignored, invalid and error mean.

Killing Survivors

Kill each survivor with a real test, or mark a genuine equivalent with # gdmutant: ignore and a reason (annotation syntax). Re-run until nothing survives. A mutation score isn't a target to hit, it's a direction to watch. There's no universal "good" number.

GitHub Actions

gdmutant also ships as a GitHub Action, so a pull request can report its own survivors. This is a complete, standalone workflow file. Save it as .github/workflows/mutation.yml. Already have a workflow and just want to add gdmutant as one more step in it? See the guide's GitHub Actions section instead, which shows the bare step on its own.

name: Mutation testing
on:
  pull_request:
  push:
    branches: [main]

jobs:
  gdmutant:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0        # `since` below needs the base commit in the clone
      - uses: kphutt/gdmutant@38f511702537fb1b27e0a93f95c5232f05eb5d66 # v0.1.6
        with:
          godot-version: "4.7.0"   # the only required input
          paths: src                # what to mutate (default: the whole project)
          runner: gdunit4            # or gut, or command
          # A PR diffs against its base commit. A merge to main diffs against the commit
          # it replaced. Either way, only the code that actually changed gets mutated.
          since: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}

It sets up Godot, installs gdmutant, and writes each survivor's gap / risk / start explanation into the job summary. The step only fails on a real error, like an already-red suite, not on survivors. Your project's existing GUT or gdUnit4 addon, and a suite that already passes, are all it needs.

The same since scoping works locally too. Adding --since origin/main to a run checks only your latest changes, for fast iteration before you commit. The Action runs it the same way in CI, so every PR gets checked automatically, even one you didn't run gdmutant against yourself.

Every input and output, and how to pin a version, is in the guide.

Compatibility

Verified at every release Expected to work
Godot 4.7.2 4.3+
Runner GUT 9.7.1, gdUnit4 6.2.3 GUT 9.x, gdUnit4 6.x, any headless command

Documentation

License

MIT, © 2026 kphutt.

Metadata

Release files for gdmutant 0.1.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gdmutant 0.1.7
File Size Uploaded Provenance Actions
gdmutant-0.1.7.tar.gz 861.0 kB With provenance Details for gdmutant-0.1.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gdmutant 0.1.7
File Interpreter ABI Platform Actions
gdmutant-0.1.7-py3-none-any.whl Python 3 none any Details for gdmutant-0.1.7-py3-none-any.whl

Total release size: 1.1 MB

Release files / gdmutant-0.1.7.tar.gz

Download URL gdmutant-0.1.7.tar.gz
Size 861.0 kB
Tags Source
SHA-256 checksum
How to use checksums
87be978a0744c8165aa32eed7d9945412990eb1a4c95ebafede16cd0a2aa269e
BLAKE2b-256 checksum
How to use checksums
50ebbb317d1e1c7aae4315c486b3c63aa9e0c545a72bd353061d2ca60a4f9792
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / gdmutant-0.1.7-py3-none-any.whl

Download URL gdmutant-0.1.7-py3-none-any.whl
Size 217.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a3c05f42d9b9f44aa75cea8ac8db21c7b0b44951385c4fe8c8c36083d7029617
BLAKE2b-256 checksum
How to use checksums
6c122e90cb7ad80b22394a03c0c2485eb842c7d6deda0369a9c766e958dbd073
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for gdmutant 0.1.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gdmutant-0.1.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page