Karate match contains vs match equals for dynamic JSON fields

Default Matcher: match contains

Use match contains as the project default for contract tests. It asserts every expected key and value — including deeply nested paths — while ignoring extra fields the server adds (timestamps, generated IDs, trace headers). This prevents false failures from dynamic data without sacrificing coverage of the declared contract.

Why match contains Protects Against Field Removal

match contains is a deep subset check. If any expected key is missing at any nesting level, the match fails. It only relaxes the "no extra keys" rule. For example:

# Expected
{ id: '#uuid', user: { name: 'Alice', email: '[contact removed]' } }

# Actual (passes — extra field ignored)
{ id: '123', user: { name: 'Alice', email: '[contact removed]' }, createdAt: '2026-11-13' }

# Actual (fails — nested email missing)
{ id: '123', user: { name: 'Alice' } }

This behavior is stable in Karate 1.0+ (current 1.4.x).

When to Override with match equals

Reserve match equals (or match ==) for endpoints whose OpenAPI/JSON Schema explicitly declares additionalProperties: false or where the team has formally agreed the contract is closed. In those cases, extra fields represent a contract violation and should fail the test.

Custom Matchers and Project-Level Overrides

Custom matchers registered via karate.configure or Java helpers add reusable predicates (e.g., #isoTimestamp, #uuid) but do not change the core semantics of contains vs equals. They apply globally, so keep predicates pure and unit-tested — a buggy predicate can silently mask failures.

If You Need "Subset + No Undocumented Fields"

Combine match contains expected with a JSON Schema validation step rather than switching to equals:

* def schema = read('contract-schema.json')
* match contains response == expected
* karate.match(response, schema)

This gives you subset semantics for dynamic fields plus strict schema enforcement for the declared contract.

Array Matching Nuance

• match contains on arrays: each expected element must be found somewhere in the actual array (deep contains, order-insensitive).
• Use match contains only when array order and cardinality must match exactly.

Verification Checklist

1. Run * print karate.version — confirm 1.0+.
2. Write a minimal feature exercising: extra fields (pass), missing nested key (fail), equals on same payload (fail).
3. Generate JSON Schema from OpenAPI spec; verify additionalProperties: false only where you intend equals.
4. Run contract suite with karate --tags @contract after changing the default.

One Diagnostic Detail

Does your OpenAPI spec already define additionalProperties: false for any endpoints? If yes, those are the only candidates for match equals; everything else stays on contains.