WitnessForge

What it does

Mainframe-to-JSON migrations are hard to test: production copies are large and contain real personal data, while hand-made test files may never exercise the tricky cases. WitnessForge takes a COBOL copybook and a declarative source-to-target mapping and generates a small set of copybook-conformant EBCDIC records, called witnesses, that catch broken mapping rules by construction.

The tool mutates each rule in the mapping specification (for example, a lost implied decimal, an ignored filter, or misaligned OCCURS elements), runs the correct pipeline and every faulty variant against candidate records at the byte level, and keeps the smallest set of records that detects the faults. It then produces a per-rule coverage score and can gate CI on a minimum score. A second command, verify, compares what a real pipeline loaded and rejected against the expected documents.

It targets ETL and data-migration teams working with fixed-width EBCDIC mainframe files, COBOL copybooks, and JSON document stores; Python 3.9+ and PyYAML are the only runtime requirements, and the code is Apache-2.0 licensed.

Quick start

Install from source until the package is published to PyPI (the README notes this):

git clone https://github.com/skavuri143/witnessforge.git
cd witnessforge
pip install -e ".[dev]"

The repository ships a full eligibility example covering every supported feature in examples/eligibility. Generate witnesses and the coverage report:

witnessforge generate examples/eligibility/member.cpy examples/eligibility/mapping.yaml -o out

generate writes fixed-length EBCDIC witnesses.dat, a human-readable witnesses.jsonl, expected loaded/rejected/filtered JSONL files, and report.json/report.md with the per-rule score. On the example, the tool reports 27 witness records detecting 163 of 163 mapping faults. Then run your real pipeline on witnesses.dat and check its output:

witnessforge verify examples/eligibility/member.cpy examples/eligibility/mapping.yaml \
    --input out/witnesses.dat --actual loaded.jsonl --rejects rejects.jsonl

Run witnessforge mutants ... first if you only want to see which faults will be checked. The same commands can be used as CI steps; --min-score 1.0 makes generate exit non-zero if any fault goes undetected.

Constraints and coverage

The mapping specification supports field decoding for text, zoned decimal, packed decimal (COMP-3), and binary COMP fields; transformations such as trim, case, substring, padding, date reformatting, lookups, arithmetic, and regex replace; validation checks for required, length, range, pattern, and allowed values; record-level filters and rejects; OCCURS arrays; and nested objects built from parallel OCCURS fields. Faults that no valid input can expose are reported as undetected, which the project treats as either an equivalent mutant or a specification gap.

Several scenarios are explicitly on the roadmap rather than supported: cross-table referential integrity, batch totals/reconciliation, change data capture and SCD history, cross-field rules, REDEFINES, OCCURS DEPENDING ON, and volume/performance testing. Unsupported copybook constructs fail loudly instead of being silently misread. Because witnesses are derived from the mapping specification, coverage is meaningful only relative to the rules you write down; the tool cannot prove behavior that the specification never describes.

HotRepo's take

WitnessForge appeared in HotRepo's new-project list for the Python language on 2026-11-08, reporting 9 stars gained over a roughly 2.5-hour window, and it has not been recorded in the all-language daily rankings. Its appeal is the concrete property it promises: a provable, minimized test set for mainframe ETL migrations, where coverage is usually guessed at. The main thing to watch is scope: the per-record mutant approach covers mapping and validation rules well, but the items still on the roadmap (referential integrity, control totals, CDC) are exactly where many real migrations break, so teams should treat a 100% score as a statement about the specified mapping rules, not the whole job.