wouldcatch 0.3.0

Quick start · The problem · What it mutates · CI and agents · FAQ

wouldcatch plants small bugs in only the lines you just changed, runs your tests after each one, and tells you which bugs got through. If your tests stay green when the code is wrong, you'll know the exact line.

Quick start

pipx install wouldcatch        # Windows without pipx: py -m pip install wouldcatch
cd your-repo
wouldcatch

That's it. No config file, no plugin, zero dependencies. It reads your git diff, runs pytest, and cleans up after itself.

JavaScript and TypeScript work the same way, with one extra piece (a parser):

pipx install "wouldcatch[js]"
cd your-repo
wouldcatch                     # runs your package.json "test" script per mutant

It handles .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts and .cts, and picks npm, pnpm, yarn or bun from your lockfile. Jest, Vitest, Mocha and node --test all work, since it only needs a command that exits non-zero when a test fails.

The problem

Two tests. Every line runs. Everything is green.

def discount(price, is_member):              def test_member():
    if is_member and price >= 100:               assert discount(200, True) == 190
        return price - 10
    return price                             def test_guest():
                                                 assert discount(50, False) == 50

$ wouldcatch
  MISSED  shop.py:2  `and` -> `or`
  MISSED  shop.py:2  `>=` -> `>`
  MISSED  shop.py:2  `100` -> `101`

4/7 caught. 3 bug(s) your tests would not notice.

Add two asserts, discount(100, True) == 90 and discount(200, False) == 200, and it's 7/7 caught.

Coverage said 100%. Coverage counts which lines ran. It can't tell you whether any test would fail if those lines were wrong. That's the question wouldcatch answers.

Why only the diff

Mutation testing is the honest way to grade tests, but running it across a whole project takes long enough that almost nobody does. wouldcatch only touches the lines in your diff. A normal change gives 5 to 30 mutants, so it's done before you finish the commit message.

What it mutates

One change at a time, only on lines in your diff. Test files are never mutated.

JavaScript and TypeScript get the same set in their own spelling: === -> !==, && -> ||, !x -> x, true -> false, return x -> return undefined, Math.max -> Math.min, if (cond) -> if (!(cond)). Type annotations, generics and JSX tags are never touched.

Want another one? New mutations are small PRs: see the good first issues.

Usage

Exit codes: 0 nothing missed · 1 something missed · 2 setup problem (not a git repo, tests already failing) · 3 incomplete: --max left mutants untried (pass --allow-partial to accept that).

A mutant whose test run times out is reported as timeout, separately from caught: a hang isn't proof that a test checks that line.

Skip a line on purpose with # wouldcatch: ignore.

CI, pre-commit and AI agents

on: pull_request
jobs:
  wouldcatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"
      - run: pip install -e . pytest   # your project and its test deps
      - uses: Sahil-u07/wouldcatch@v0.3.0

- repo: https://github.com/Sahil-u07/wouldcatch
  rev: v0.3.0
  hooks:
    - id: wouldcatch

After changing Python, JavaScript or TypeScript code, run `wouldcatch --json`. For every mutant with
"status": "missed", add a test that fails for that change. Re-run until none are missed.
Never change the source code to make a mutant go away.

How it works

git diff ──> changed lines ──> mutants ──> run tests per mutant ──> restore file ──> report

1. git diff gives the Python, JavaScript and TypeScript lines you changed.
2. Each mutant is a tiny text edit at an exact position, so your formatting and comments stay untouched.
3. Your test command runs once per mutant. A fresh bytecode cache each run means a stale .pyc can never hide a mutant.
4. The file is restored byte for byte (CRLF included) after every run, even on Ctrl+C. If the process is killed, the next run restores it from a backup kept inside .git first.

FAQ

Contributing

PRs welcome, especially new mutations. Start with a good first issue and read CONTRIBUTING.md.

If wouldcatch found a bug your tests missed, a star helps other people find it.

MIT · made by Sahil Lenka