A Stub Matching on JSON Path That Fires on the Wrong Request

Quick answer

Over-specific body matching is a quiet source of false positives in a mock. A stub that matches on a JSON path expression, or on a long list of exact fields, can fire on a request it was never meant for when another payload happens to contain the same nested value, and it can equally fail to fire on the intended request when one irrelevant field differs. The result is a mock that returns the wrong response intermittently. Keep matchers narrow and targeted to the fields the stub actually depends on, use equal-to on the minimal structure rather than the whole body, and add tests that prove the stub does not match a near-miss request.

How the wrong request fires the stub

Consider a stub intended for a payment capture, matched on a nested path rather than the full identifying context.

Two different request types now collide. A payment and a refund adjustment both post to a path with amount of 100.00, so the stub matches both, even though the surrounding intent differs.

The matcher only looked at one nested value and ignored the discriminator that separates the two operations, so the second request receives the capture response.

Why whole-body matching fails in the other direction

The opposite habit is matching the entire request body exactly. That is precise until the client adds a harmless field or changes a value the stub does not care about, at which point the stub stops matching and the request falls through to a default 404. Teams then loosen the matcher reactively, often overshooting into the collision problem above. Both failures come from the same root cause: the matcher is not scoped to the minimal set of fields that actually determine the response.

Matching style	Failure mode	Characteristic
Single JSON path, no discriminator	Matches unrelated requests	False positive
Whole body exact equality	Stops matching on any field change	False negative
Minimal targeted fields	Stable when irrelevant fields change	Preferred
Path plus type discriminator	Separates operations sharing a value	Robust

Scoping the matcher to what matters

Identify the fields that actually distinguish the scenario and match on those, allowing the rest to vary. When two operations share a value, include the field that discriminates them, such as the request type, rather than relying on the shared nested value alone.

For a spec-driven mock this discipline follows naturally from the contract: the response is determined by the operation and the documented key fields, not by incidental payload content. Matching on that minimal set keeps the stub tolerant of additive changes while still discriminating the intended case.

Proving behavior with negative tests

A matcher is only trustworthy if you test what it should reject. Send the intended request and confirm it matches, then send a near-miss that shares the matched value but differs in the discriminator, and assert the stub does not fire. Include a request that adds an irrelevant field to confirm the targeted matcher still matches, guarding against regression into whole-body equality. These tests turn the intermittent wrong-response problem into a deterministic check and make the matcher's boundaries explicit. In a large mock suite, they also catch a later edit that loosens a matcher and reintroduces a collision.

Priority and scenario-based matching

Even with well-scoped matchers, a request can legitimately satisfy more than one stub, and the mock needs a deterministic rule for which one wins rather than relying on insertion order. Explicit priority lets the most specific mapping take precedence over a broad fallback, so a precise capture response wins over a generic default while the fallback still catches everything else. The danger of leaving priority implicit is that adding a new mapping later can silently change which stub an existing request hits, which is a particularly hard regression because the old tests may still pass if they only check one path. For stateful workflows, scenario-based matching ties the response to a named state that advances as requests arrive, which is the correct way to model a sequence rather than trying to encode the entire history into one body matcher. Combine these with the same negative-test discipline: send a request that could match two stubs and assert the priority-selected one responds, and walk a scenario forward to confirm the state transitions. Keeping priority explicit and state separate from body matching makes a complex mock predictable even as mappings are added over time.

Audit and ownership

As mock mappings accumulate, periodically audit them for overlapping matchers, much as you would find dead stubs. Two mappings that can match the same request are a configuration defect even if the current tests do not expose it. Keep each mapping traceable to a scenario in the spec and prefer a small number of well-scoped matchers over a pile of broad ones. The goal is a mock whose response is predictable for every request, not just the exact happy path.

FAQ

Is JSON path matching inherently unsafe?

No. It is expressive and useful, but a single path without the discriminating context is too broad. Combine paths that identify the operation and the key fields, and test the near-miss case to confirm the boundary.

Why not just match the whole body to be safe?

That is safe only against false positives, and it makes the stub brittle so any irrelevant change breaks it. The mock then needs constant edits, and broad loosening under pressure tends to cause collisions. Targeted fields avoid both extremes.

How can I tell if two stubs overlap?

Run a set of representative requests and record which stub each one hits, and audit matchers that share a path or value without a discriminator. A request that could satisfy more than one mapping is the thing to look for.

Does a spec-based mock avoid this automatically?

It helps because matchers are derived from the operation and its documented fields rather than hand-written, but loose custom additions can still overfit. Keep manual matchers scoped to the contract and verify them with negative tests.

This is part of the Powerduck vs WireMock: Spec-First vs Code-First Mocking — start there for the full picture of keeping mocks precise and trustworthy.