# Flawd

> Flawd is a mutation testing CLI tool that plants small, realistic bugs in your code to check whether your test suite would actually catch them, exposing blind spots in your coverage.

Flawd is a mutation testing tool built by Fixture Dev, LLC for developers who want to know whether their test suites would actually catch a bug — not just whether lines of code ran. It runs entirely on your local machine or in CI, with no cloud service behind it, and produces HTML, JSON, SARIF, and Markdown reports that both humans and coding agents can consume.

## What It Is

Mutation testing is a technique that measures test quality by making small, deliberate changes to source code — called mutants — and checking whether the test suite fails. A mutant that survives (i.e., the tests still pass) reveals a blind spot: code that runs under test but is never meaningfully verified. Flawd automates this loop for JavaScript, TypeScript, Python, Go, and Rust, using tree-sitter for parsing and Docker for isolated, reproducible test runs.

## How the Mutation Loop Works

Flawd's workflow has four stages, all triggered by a single command (`flawd run`):

- **Plant** — Flawd parses your code with tree-sitter and injects mutants only into lines already covered by your existing tests, so no time is wasted on unreachable code.
- **Test** — Your test suite runs against each mutant inside an isolated Docker container (Podman and OrbStack also work). A test that fails kills the mutant; a test that passes means the mutant survived.
- **Report** — Survivors are flagged with a diff, a risk level, and a category. Reports ship in HTML for humans, JSON and SARIF 2.1.0 for pipelines and GitHub Code Scanning.
- **Hand off** — `flawd handoff` packages every survivor — diff, source context, covering tests, and fix guidance — into a Markdown file a coding agent can read to write the missing assertions.

## Why It Targets the AI-Era Test Problem

Fixture's stated rationale is that AI coding agents produce high coverage quickly by mirroring code structure rather than verifying behavior. The result is test suites that run everything and assert little. Flawd is positioned to close that loop: it finds the assertions that aren't there and gives the agent a structured handoff to write them.

## Deployment Model: Local-First, CI-Ready

There is no server or cloud component. Flawd ships as a single self-contained binary for Linux (x86_64, ARM64, musl static), macOS (Apple Silicon and Intel), and Windows (via WSL2). Installation is a one-line curl script or a manual download. Key operational details:

- **Incremental caching** — SQLite-backed cache between runs; `--diff` scopes mutations to lines changed since any git ref, keeping runs short enough to sit between commits.
- **CI gate** — `flawd ci --threshold N` exits non-zero when the mutation score drops below a configured bar, scoped to the pull request diff, with SARIF output for GitHub Code Scanning.
- **Flaky test handling** — configurable baseline retries (`--baseline-retries`), with errored mutants excluded from the mutation score.
- **Parallelism** — eight Docker workers run concurrently by default.

## Language and Coverage Support

Five languages are supported through tree-sitter parsing: JavaScript, TypeScript, Python, Go, and Rust. Coverage input is accepted as LCOV, Cobertura XML, or Go coverprofile — whatever the existing test runner already produces. This means Flawd slots into an existing workflow without requiring instrumentation changes or a new pipeline.

## Update: v5.3.2 (go-chi/chi context note)

The GitHub metadata linked in the seed points to go-chi/chi, an unrelated open-source Go HTTP router. The selected project homepage is fixture.dev/flawd, which is the correct product page for Flawd. Flawd itself does not publish a public version number on its homepage; the go-chi/chi v5.3.2 release (August 2026) is not a Flawd release and should not be attributed to it.

## Features
- Mutation testing across JavaScript, TypeScript, Python, Go, and Rust
- tree-sitter parsing for accurate, language-aware mutant generation
- Coverage-driven mutation: only mutates lines covered by existing tests (LCOV, Cobertura, Go coverprofile)
- Docker-isolated test runs for reproducible, side-effect-free results
- Live terminal dashboard showing score, survivors, and worker activity
- HTML report with per-mutant status, operator, diff, and runtime
- JSON and SARIF 2.1.0 output for pipelines and GitHub Code Scanning
- flawd handoff: packages survivors into a Markdown file for coding agents
- SQLite-backed incremental caching between runs
- -diff flag to scope mutations to lines changed since any git ref
- flawd ci --threshold N for CI gating with non-zero exit on score drop
- Flaky test detection with configurable baseline retries
- Eight parallel Docker workers
- Single self-contained binary: no runtime or package manager required
- flawd upgrade command for in-place updates
- No cloud service: all processing runs locally on your hardware

## Integrations
Docker, Podman, OrbStack, GitHub Code Scanning (SARIF), LCOV coverage format, Cobertura XML coverage format, Go coverprofile, git (diff scoping), CI pipelines (generic), Coding agents (Markdown handoff)

## Platforms
WINDOWS, MACOS, LINUX, IOS, WEB, API, CLI

## Pricing
Paid

## Links
- Website: https://fixture.dev/flawd
- Documentation: https://support.fixture.dev/hc/en-us
- Repository: https://github.com/go-chi/chi
- EveryDev.ai: https://www.everydev.ai/tools/flawd