WorksRight — Prove your tests actually work

WorksRight is a QA intelligence tool for TypeScript/React/Next.js projects. It detects anti-patterns that make tests meaningless (assertion-free tests, mocked databases, over-mocking), runs mutation testing to verify tests can actually catch real bugs, and generates behavior-verifying test scaffolds. The result is a scored quality report showing exactly where your test suite lies about coverage and what to fix first.

Quick Start

npm install -g worksright
# Or use as MCP tool with Claude Code:
# Add to .mcp.json: {"mcpServers": {"worksright": {"command": "npx", "args": ["worksright"]}}}

Usage as MCP Server

Add to your .mcp.json:

{
  "mcpServers": {
    "worksright": {
      "command": "npx",
      "args": ["worksright"]
    }
  }
}

Available tools:

| Tool | Description | |------|-------------| | worksright.scan | Detect project type, framework, test framework, and database | | worksright.detect_antipatterns | Find anti-patterns in test files with file paths and line numbers | | worksright.run_mutations | Run Stryker mutation testing and return a kill rate | | worksright.generate_tests | Scaffold behavior-verifying test skeletons for untested source files | | worksright.report | Generate a scored quality report combining all three dimensions |

Usage as CLI

npx worksright scan /path/to/project

This runs the full scan + anti-pattern detection and prints a summary. Pass --output ./reports to write JSON and Markdown report files.

Anti-Patterns Detected (12 types)

| Pattern | Severity | What It Means | |---------|----------|---------------| | assertion-free | Error | Test has no expect() calls — it always passes regardless of behavior | | mocked-database | Error | Database layer is mocked (Supabase, Prisma, Drizzle, etc.) — hides N+1 queries, constraint violations, and transaction bugs | | trivial-assertion | Warning | Only uses presence checks (toBeDefined, toBeTruthy) — proves the function ran but not that it did anything correct | | over-mocking | Warning | More than 5 mock definitions in a single file — likely testing mock scaffolding, not real behavior | | implementation-coupled | Warning | Uses Enzyme-style internals (.state(), .instance(), .props()) or querySelector with CSS classes/IDs — breaks on refactors | | hardcoded-wait | Warning | Uses setTimeout/sleep with a fixed millisecond value — makes tests slow and flaky on CI | | snapshot-overuse | Warning | >50% of assertions are toMatchSnapshot() — changes get rubber-stamped via --update | | non-deterministic | Warning | Tests depend on new Date() or Math.random() — flaky across runs | | happy-path-only | Warning | No error cases, invalid input, or boundary tests in a file with 3+ tests | | test-pollution | Warning | Module-level mutable variables modified in tests without beforeEach/afterEach cleanup | | excessive-setup | Info | beforeEach/beforeAll block exceeds 30 lines — test intent is buried | | copy-paste-setup | Info | Near-identical setup blocks across describe blocks — extract to a shared factory |

Benchmark Results

Validated against a calibration corpus of 9 bad-pattern files and 3 clean files:

| Dimension | Score | Target | Status | |-----------|-------|--------|--------| | Anti-pattern detection F1 | 1.000 (14 TP, 0 FP, 0 FN) | 0.80 | Pass | | False positive rate | 0% (0 FP on 3 clean files) | <5% | Pass | | Pattern coverage | 12/12 types implemented | 100% | Pass | | Tests passing | 126/126 | 100% | Pass |

Integration tested against 3 real-world codebases:

| Target | Files Scanned | Findings | Time | |--------|--------------|----------|------| | id8-web (Next.js, 85 deps) | 36 | 121 | 982ms | | ResumeWise (Next.js) | 25 | 24 | 2.9s | | iD8 (Node.js, 358 test files) | 358 | 1,716 | 12.2s |

How It Works

worksright.scan
  └── Detects framework, language, test framework, database, package manager

worksright.detect_antipatterns
  └── Parses test files with ts-morph AST
  └── Runs 12 pattern detectors, returns findings with file:line locations

worksright.run_mutations
  └── Configures Stryker for the target project
  └── Returns kill rate, survived mutants, and no-coverage count

worksright.report
  └── Combines anti-pattern health (40%) + mutation coverage (35%) + test presence (25%)
  └── Scores 0–100, assigns grade A–F, flags critical issues
  └── Writes Markdown + JSON report with Top Issues and Next Steps

Development

npm run build    # Compile TypeScript to dist/
npm test         # Run all tests with Vitest
npm run lint     # Type-check without emitting (tsc --noEmit)
npm run dev      # Run the MCP server directly with tsx (no build step)

Tests live in tests/ and cover the anti-pattern detectors, scanner, reporter, and benchmark runner. The benchmark corpus is in benchmarks/corpus/ with bad/ and good/ subdirectories containing annotated test files.

Requirements

• Node.js >= 20
• TypeScript projects (uses ts-morph for AST analysis)
• For mutation testing: the target project must have @stryker-mutator/core and a compatible runner installed