parity-tests.json

parity-tests.json defines the behavior preservation test inventory. Parity testing is the mechanism that ensures modernized code behaves identically to the legacy system. Without parity tests, migration is guesswork.

Full Example

{
  "strategy": "behavior-preservation",
  "suites": [
    {
      "context": "Accounts",
      "tests": 68,
      "type": "functional-parity",
      "command": "bun test src/accounts/",
      "baseline": "legacy-snapshots/accounts/"
    },
    {
      "context": "Tax",
      "tests": 24,
      "type": "functional-parity",
      "command": "bun test src/tax/",
      "baseline": "legacy-snapshots/tax/"
    },
    {
      "context": "Stock",
      "tests": 0,
      "type": "functional-parity",
      "command": "bun test src/stock/",
      "baseline": "legacy-snapshots/stock/"
    }
  ],
  "acceptance": {
    "parity_threshold": 0.95,
    "regression_tolerance": 0
  }
}

Field Reference

Root Fields

Field	Type	Required	Description
`strategy`	`string`	Yes	Testing strategy: `"behavior-preservation"`, `"contract-driven"`, `"shadow-testing"`

`suites` Array

Each entry describes a parity test suite for a bounded context:

Field	Type	Required	Description
`context`	`string`	Yes	The bounded context this suite covers
`tests`	`number`	Yes	Number of tests in the suite
`type`	`string`	Yes	Test type: `"functional-parity"`, `"data-parity"`, `"api-parity"`
`command`	`string`	Yes	Command to run the test suite
`baseline`	`string`	Yes	Path to legacy behavior snapshots/recordings

`acceptance` Object

Field	Type	Required	Description
`parity_threshold`	`number`	Yes	Minimum parity percentage (0.0 to 1.0). `0.95` means 95% of tests must pass.
`regression_tolerance`	`number`	Yes	Number of regressions allowed. `0` means zero tolerance for regressions.

Test Strategies

Behavior Preservation (Recommended)

The default strategy. Each legacy business rule maps to a test that verifies the modern implementation produces identical output.

Dimension	Method
Data model	Field-by-field mapping (legacy schema to modern struct)
Business rules	Rule-by-rule comparison with test evidence
Error handling	Legacy exception to modern error mapping
Edge cases	Table-driven tests covering boundary conditions
Integration	Realistic data from the legacy system

Contract-Driven

Define expected behavior as contracts. Both legacy and modern systems must satisfy the same contracts. Uses tools like Pact.

Shadow Testing

Run both systems in parallel with real traffic. Compare responses. Uses tools like Diffy or GoReplay.

Test Type Details

Type	What It Verifies	Example
`functional-parity`	Business logic produces identical output	Tax calculation returns same amounts
`data-parity`	Data structures match between systems	GL entries have same fields and values
`api-parity`	API responses are identical	Same request produces same JSON response

Baseline Snapshots

The baseline path points to captured legacy behavior. This can be:

JSON snapshots of legacy API responses
Database dumps of legacy computation results
Recorded test data from the legacy system
Golden files with expected outputs

These baselines serve as the source of truth for parity verification.

Acceptance Thresholds

Parity Threshold

0.95 (95%) is the recommended starting threshold. This allows for minor differences in formatting, whitespace, or precision while catching functional regressions.

A threshold of 1.0 is appropriate for financial calculations where exact precision matters.

Regression Tolerance

0 is recommended. Any test that was previously passing should never start failing. If a change causes a regression, it must be fixed before merging.

Agent Behavior

After modifying any extracted module:

Read parity-tests.json to find the relevant test suite
Run the command specified in command
Compare results against the acceptance thresholds
If tests fail below threshold, the modification should not be considered complete

Next Steps

migration-state.json — Track progress
Progress Dashboard — Interactive visualization