mutate4js

Mutation testing for JavaScript/TypeScript. Discovers mutation sites, applies each one, runs your tests, and reports killed, survived, and uncovered mutations — with an embedded-in-source manifest so differential reruns survive a clone with zero CI setup.

A faithful JS/TS port of unclebob/mutate4go. Where the JS ecosystem forces a divergence (coverage acquisition, parallel-worker node_modules handling) it is marked [JS] and justified in docs/mutate4js-spec.md.

The CRAP gate in CI uses @gabadi/crap4js, a JS/TS-native CRAP analyzer in the same lineage as Robert C. "Uncle Bob" Martin's crap4clj — the original Clojure implementation whose report format and metric semantics it follows most closely.

Status: early, dogfooded. Full CLI, mutation manifests, and CI gates are working.

Install

bun add -d mutate4js   # or: npm i -D mutate4js

Usage

mutate4js path/to/file.ts --test-command "bun test" --cov-cmd "bun test --coverage"

See mutate4js --help and the spec for the full flag set.

Develop

Built with Bun. Parser: @typescript-eslint/typescript-estree.

bun install
bun run src/cli.ts --help
bun test

Releasing a New Version

Releases are manual. The release workflow runs on version tags — it does not trigger on merges to main.

1. Bump the version in package.json.
2. Commit, tag, and push:

   git commit -am "chore: release vX.Y.Z"
   git tag vX.Y.Z
   git push origin main
   git push origin vX.Y.Z

3. The release workflow triggers on the tag push, re-runs the full CI gate sequence, and creates a GitHub Release at https://github.com/gabadi/mutate4js/releases/tag/vX.Y.Z.
4. Publish to npm:

   npm publish --access public