How to test merchant enrichment with deterministic fixtures.

A good fixture tests evidence, not just typography. Asserting only that a descriptor becomes a prettier display name misses the behaviors that make enrichment safe: privacy rejection, reviewed-match boundaries, confidence bands, signals, warnings, and omission of unsupported websites or logos.

recognized: PAYPAL *SPOTIFY
unresolved: SQ *JOES COFFEE 0421 TORONTO
rejected:  PAYPAL *SPOTIFY\nSQ *JOES COFFEE\nCARD PURCHASE

These three cases exercise different contracts. A recognized descriptor proves deterministic matching. An unresolved descriptor proves bounded fallback behavior. A rejected payload proves that privacy validation happens before parsing and enrichment.

Fixture shape

[
  {
    "case": "recognized merchant",
    "input": {"raw_description": "PAYPAL *SPOTIFY", "country": "US"},
    "assert": {"status": 200, "display_name": "Spotify", "confidence_at_least": 0.90, "signal": "reviewed_merchant_match"}
  },
  {
    "case": "unresolved merchant",
    "input": {"raw_description": "SQ *JOES COFFEE 0421 TORONTO", "country": "CA", "mcc": "5814"},
    "assert": {"status": 200, "website": null, "logo_variants": 0, "warning": "local_merchant_identity_not_verified"}
  },
  {
    "case": "statement-like rejection",
    "input": {"raw_description": "PAYPAL *SPOTIFY\nSQ *JOES COFFEE\nCARD PURCHASE"},
    "assert": {"status": 400, "error_code": "statement_like_input"}
  }
]

Keep rejected fixtures synthetic. The three-line example is made from safe sample descriptors, but it still exercises the implemented statement-like-input guard. A test suite does not need real card numbers, account numbers, customer names, contact details, or statement exports to prove that rejection works. Generate obviously fake boundary cases and make sure test output does not echo sensitive-looking payloads.

Also assert invariants across cases: the same input produces the same parsed signals and response shape; low-confidence matches do not acquire websites or reviewed logos; and errors stay bounded. The TxnKit benchmark provides public before/after examples, while the OpenAPI contract defines the response fields.

When to use it

Use deterministic fixtures during parser changes, seed updates, alias promotion, confidence tuning, API contract changes, and deployment smoke tests. Add a regression fixture whenever a real anonymized descriptor exposes a new failure mode and the evidence is safe to retain.

When not to use it

Do not present a small fixture set as a market-wide accuracy score or coverage claim. Do not make every assertion an exact decimal confidence value if the stable contract is a band, warning, or omission rule. Fixtures verify known behavior; they do not replace representative evaluation.

Privacy caveat

Fixtures belong under the same privacy boundary as production input. Never copy card numbers, account numbers, bank credentials, customer PII, full statements, emails, phone numbers, or addresses into source control, snapshots, logs, or test failure messages. Use anonymized descriptors and synthetic rejection cases.