Legacy code test harness: characterization tests for untested Python and JS code

What it does

Makes untested legacy code safe to change by recording what it does today and pinning that behavior with characterization (golden master) tests.

• Function inventory and risk ranking (inventory.py): per function and method it measures size, branching complexity (Python AST; a heuristic scanner for JS/TS), fan-in from other files, whether tests mention it, and git churn, then ranks what to test first. It also flags dependencies on files, network, databases, the clock and randomness
• Test tooling detection: pytest, unittest, jest, vitest, mocha, config files, TypeScript, coverage tools and the commands to run them
• Record real inputs and outputs (record_calls.py, record-calls.cjs): while you run the program or its existing tests as usual, it saves arguments, return values or exceptions, and changes to arguments and object state as JSON (Python and CommonJS Node.js)
• Test generation (gen_characterization.py): pytest, jest or vitest tests that replay the recorded cases. Functions without recordings get placeholder inputs guessed from parameter names, clearly marked for replacement. Handles methods, async functions, ESM and CommonJS, and TypeScript. Existing files are never overwritten
• Coverage gaps (coverage_gap.py): combines coverage.py, Cobertura, LCOV or Istanbul results with the ranking to list risky functions that never run
• Guides and templates: a step-by-step procedure for capturing behavior before refactoring, how to freeze time, randomness, environment and network in pytest, jest and vitest, hand-written test examples, a report template, and three sample projects with a worked example

How to use

python scripts/inventory.py . --json inventory.json --md inventory.md
python scripts/gen_characterization.py --inventory inventory.json --top 5
python scripts/record_calls.py --root . --target shop.pricing:calc_total --out tests/characterization/cases -- main.py

The agent picks targets from the planned change and the ranking, assembles recorded and hand-written cases, runs the tests twice to confirm they are stable, makes a small deliberate change to confirm the tests catch it (then reverts it), and reports remaining gaps and any suspicious current behavior. Works with Claude, Codex, Hermes Agent and Cursor.

Requirements

• Python 3 for the scripts (standard library only); git for churn (optional); Node.js for recording JavaScript calls
• The generated tests need the project's test runner (pytest, jest or vitest). Coverage needs pytest-cov or the runner's coverage option

Caveats

• JS/TS parsing and the risk score are heuristics. Placeholder inputs are guesses and must be replaced with real values
• Recording runs the program for real (file writes, network calls). Use a test environment and check recorded JSON for personal data
• ESM JavaScript cannot be recorded automatically; write those cases by hand
• Bugs found along the way are reported, not silently fixed