Collaborative contracts - a proposed update to the contract testing methodology

[mefellows]

NOTE: this proposal was taken from the #feature-requests channel from the Slack workspace to improve visibility.

Author: @DanielWillian

TL;DR:

I’m proposing a way for consumers to verify they exercised all interactions in a shared pact.json, even if they didn’t generate it.
Pact already supports provider verification from a pact file; this would add optional support for consumer-side verification by failing tests if any interactions weren’t used.
It’s a small step toward bi-directional confidence, without compromising the consumer-driven philosophy.

Proposal
Hey all 👋, I have a proposal that I think could complement Pact’s philosophy while supporting teams working in highly collaborative environments.

In some cases, teams may want to mutually agree on a shared pact.json file, hand-written, but collaboratively authored and version-controlled, and use it as a behavioral contract.

This allows both sides to contribute: the consumer knows what it wants, but the provider knows what it can do.
It would be really helpful if Pact supported workflows for teams that want to validate both sides of such a contract, even when the consumer isn’t generating the pact file through tests.

Right now, Pact already fully supports the provider side of this setup, but not the consumer side.
In this verification approach, the consumer would:

• Spin up a stub/mock server from the shared pact (as Pact already allows)
• Run consumer tests against that stub (doesn’t require Pact support)
• Fail the test suite if any interactions in the pact were not exercised (not currently supported, but would be really helpful)

The goal is to ensure the consumer really uses what the pact says it does, just like it does with the provider.
I know Pact is consumer-driven and discourages hand-written contracts, mainly because people might rely on the contract instead of verifying their usage through real tests, and I fully agree with that philosophy.
This proposal isn’t about skipping tests, it's about adding strictness to ensure the consumer truly adheres to the shared contract. It's a small step toward bi-directional testing without compromising the core consumer-driven model.
I’m asking because Pact provides the strongest confidence in contract testing available today — thanks to its precise request/response mapping (not just schema validation) and the compatibility matrix enabled by can-i-deploy.

Creating a new tool just to support this small bi-directional need feels like a waste when Pact is already so close to solving it.

Would this be a welcome addition to the tooling, for example, a flag in the mock server or test library that serves only one interaction at a time, to force full coverage?

Or is this too far outside Pact’s intended model?

[mefellows]

NOTE: these responses were taken from the above conversation, and copied here by Matt Fellows so as to retain history. The names of the participants have been kept inline

Matt Fellows
It’s an interesting idea (and something discussed previously, although likely lost to our slack history).
I’d certainly be open to you putting together a prototype and trying it out in the real world (often times, this is where the real value is felt or pain is discovered). I think most of the infra is there, as you say.
One issue, is that the Pact Broker currently doesn’t have a (first-class) way for a provider to publish it’s own provider contract (effectively that’s what it is). But you could probably handle that by creating a faux consumer, and pull the contract from it.

Fail the test suite if any interactions in the pact were not exercised (not currently supported, but would be really helpful)

if you were to remove this constraint, you could create a more “provider driven” workflow. What you could do is:

1. Load the pact.json file into the mock server
2. Record any interactions that match
3. Spit out a contract that is now a subset of pact.json
4. The rest of the workflow is as per usual Pact

Joshua Ellis
Depending on how the prototype goes and how the idea gets fleshed out, this could become a candidate for a more formal RFC
The idea of using Pact as a contract specification in and of itself is interesting, which of course opens up the verification of not just consumers, but also consumers.
I think the biggest hurdle, as Matt pointed out, is around the management of the 'source of truth'. Maintaining a pact.json file by hand does not feel right, and flipping the model to be provider-driven also does not feel right (afterall, just because I can query an endpoint does not mean that I must).
This last point I think is worth elaborating on. The reason Pact is consumer driven is that consumers make the requests with some expectation of what to get in return. Just because a provider has a path to /some/obscure/deprecated/endpoint should not then cause the consumer to fail because it did not make a request to that endpoint.
I'm curious to hear your thoughts here.

Daniel Willian
Thanks! I appreciate the thoughtful response.
At this moment, I’m not even asking for full support within the Pact Broker, just a way for this workflow to work when teams already have the contract as an artifact (e.g., committed to a repo or downloaded manually).
I agree that a “subset contract” approach is technically possible, load the pact, track matched interactions, and output a trimmed pact.

But this doesn’t fail the test if something is missing, and usually requires extra setup code that's unrelated to the business test itself.
That’s the small piece I’m hoping for: a minimal support mechanism to help consumer tests assert coverage of a shared contract, keeping test logic clean and focused. It would make this workflow feel native to Pact, not duct-taped onto it.
Coming from the Java world, I imagine an implementation could look something like this:

• Use a @State("some description") annotation on each test, mapped to a specific interaction in the pact
• During test execution, track which interactions were matched
• At the end of the test suite, fail if any pact interaction was not exercised

This would keep the test code clean and expressive, while still enforcing strict validation — and would make this workflow feel native to Pact, not bolted on externally

Joshua Ellis

(haha, messages have crossed)
One last thing I would mention is that when a consumer sets up the interactions to be verified, the subsequent test must test every interaction defined in that test. This is typically to allow for multi-query actions (e.g., perhaps a DELETE always has a GET to ensure the right resource is being deleted).

Taking that existing mechanism to its extreme, you could read the pact.json to set up all the interactions, and then run the test suite against the Pact server to ensure all interactions succeed. This may in fact achieve what you want.
This feature of Pact is by design, and is part of the compatibility suite.

Daniel Willian

Absolutely, I completely agree that the strength of Pact is its consumer-driven model, and I’m not proposing flipping it to be provider-driven.
What I’m describing is a third path: a shared, collaboratively-authored contract that both teams agree on, for example, a pact.json committed to a shared GitHub repo where both the consumer and provider teams are listed as owners.
This isn't about saying "the provider defines what’s available" — it's more like:
"Here’s what we’ve agreed the consumer depends on and the provider guarantees."
In that sense, it's still consumer-led — because only interactions the consumer claims to use are in the contract — but the contract itself might be:

• Derived from a consumer test
• Agreed upon through collaboration (e.g., in an interface meeting)
• Reviewed and maintained jointly

The reason I’m asking for consumer-side interaction verification is not to force consumers to match the provider’s full API (which would break everything), but to ensure that when both sides have agreed to a set of interactions, the consumer actually exercises all of them — and nothing silently gets left behind.
So I fully agree: this should never fail because of some unused, deprecated endpoint the consumer doesn’t care about. But if there are five agreed-upon interactions in a pact file, and the consumer only hits three during testing, that’s worth flagging — especially in collaborative environments.
When adding or removing interactions, both teams have to be aware and approve.
If the prototype proves useful, I’d definitely be open to working on a more formal RFC. The goal would be to enhance Pact's flexibility while staying faithful to its core philosophy: test what you use, guarantee what you return.

Matt Fellows

In practice, having all consumers adhere exactly to the same contract is usually very difficult - it requires all of them to synchronise changes.
Is this actually desirable, or just part of the current proposed solution? That is, why would it be an issue if a consumer didn’t call an endpoint? The classic example I go to here are mobile applications - you have an Android and iOS app in native languages, maintained by two teams. This creates places for 2 divergences

1. One team may move faster than another
2. One team may need slightly different things (a real life example was when I was working for a banking provider, they needed to support different payment tokens for apple and google pay and the configuration endpoints were different)

Personally, I think the idea of a provider contract (that is shared/authored) and a consumer contract (that tracks the specific differences) might be another approach.

The provider contract says “here is all of the APIs and scenarios I support” and the consumers each use a subset of them. This way, the verification is much faster (it just happens once and they get to control that process). The consumer contract is effectively “did you use test scenarios from this contract?“.

Daniel Willian

I agree. I also think your idea of a provider-authored superset + consumer overlays is compelling — but that would be a much bigger shift, requiring changes to the Pact file format, how verification works, and how can-i-deploy interprets compatibility.
That’s a heavy lift, and possibly worth exploring in the long term.
But in contrast, this proposal fits entirely within the existing model and format — just an opt-in verification mode to help consumers enforce their own accuracy.
I agree consumers shouldn’t be forced to use all of a provider’s contract, and in complex systems, it’s totally expected that teams move at different speeds or need different capabilities. Pact already handles that well through versioning and can-i-deploy. And the shared contracts are versioned as well.
But in the workflow I’m describing, the contract isn’t authored by the provider, it’s a pact.json that the consumer themselves agreed to and published. So the concern isn’t that the consumer must fulfill some arbitrary external spec — it’s that:
If the consumer stops using part of what they said they use, there’s no signal — not from can-i-deploy, not from provider verification, and not from consumer tests unless they explicitly clean up the shared pact.
That’s the danger: the illusion of coverage. The pact becomes stale, but no one notices.
What I’m suggesting is:

• Don’t force consumers to use everything the provider supports
• But allow consumers to assert that they exercised all the interactions they’ve declared in their own pact
• And if they stop using one, they should remove it — which is already part of good contract hygiene

This isn’t about enforcing a provider-driven model — far from it. It’s about giving consumer teams more tooling to enforce the contracts they authored, and keep them clean, the same tools that exist on the provider side.
If that works well, it could evolve naturally and maybe even feed into longer-term ideas like a formal RFC for collaborative contracts or bi-directional overlays.

Matt Fellows

But in contrast, this proposal fits entirely within the existing model and format — just an opt-in verification mode to help consumers enforce their own accuracy.

This is a very helpful (and pragmatic) clarification, thanks.

That’s the danger: the illusion of coverage. The pact becomes stale, but no one notices.

Yes, as you say, that’s a problem today anyway. It’s hard to automate your way around it (maybe the consumer is just really stable and doesn’t change?). PactFlow AI aims to help with this because it will (soon) review code and compare against tests to generate recommended fixes (i.e. gaps that need filling, or over specifying).
Back to your idea. I think it’s a prototype worth exploring - is it something you’re up for giving a crack?

Daniel Willian

Yeah, I’m definitely up for giving it a crack, though I’m not sure exactly when 😅
It could be next week, or it could be a few months from now. I mainly wanted to confirm there was genuine interest before putting time into it, and it’s great to see that there is.
That said, I don’t see any issue with multiple people exploring this in parallel. I’d be more than happy to collaborate, share ideas, or support anyone else who wants to jump in sooner. It feels like a valuable addition, and I’d love to see it move forward however it happens.
:party_parrot:

Matt Fellows

That said, I don’t see any issue with multiple people exploring this in parallel. I’d be more than happy to collaborate, share ideas, or support anyone else who wants to jump in sooner. It feels like a valuable addition, and I’d love to see it move forward however it happens.

totally agree.

Fail the test suite if any interactions in the pact were not exercised (not currently supported, but would be really helpful)

I believe this capability might already exist. This function accepts a fully formed Pact JSON and would behave as per the usual mock server rules - any interactions not exercise will fail the test.
One consideration you would need to ensure there are no overlapping interactions in the pact file when loading into the mock server.

1. e.g. provider states won’t be very helpful in allowing you to test the 200 and 404 use case for GET /users/xyz, because the mock server won’t know which one you want
2. Perhaps this could be addressed with warnings (or even errors?) if overlapping scenarios are detected when loading the server

Also, I propose moving this conversation to a github discussion. I’ll do that today (the reason being is that this slack workspace has a free tier conversation limit, and I don’t want to lose the great work here to the trash can)

Daniel Willian

Oh, interesting, I wasn’t aware the mock server already fails when interactions aren’t exercised. That’s really helpful to know!
Just to share some context: in our consumer tests, we were using the pactfoundation/pact-stub-server Docker image inside a Testcontainers setup in Java. We mounted our pact.json into the container and pointed our client at the stub server like this, but programmatically in Java:

docker run --rm \
  -v $(pwd)/pacts:/pacts \
  -p 1234:8080 \
  pactfoundation/pact-stub-server:latest \
  /pacts

From what we observed, the tests would still pass even if we only exercised a subset of the interactions, which led us to believe that unused interactions weren’t being validated. Knowing now that this behavior is enforced by the stub server makes me think we may have missed something in the way we were using it.
That brings me to a question: Is this "fail on unused interactions" behavior exposed in Pact JVM natively, or is it currently specific to the Rust-based stub server?
We didn’t see any documentation in the Pact JVM or Testcontainers guides about the Rust stub server, so it wasn’t clear whether using it directly was the intended or supported path for consumer-side testing in Java. If there’s a more idiomatic way to do this using Pact JVM itself, I’d love to learn about it. And if not, maybe this is a gap worth bridging.
Also, regarding overlapping or conflicting interactions (e.g., same method/path but different response codes), I’d be in favor of the stub server erroring out on load in those cases. I think early failures here would be helpful and promote cleaner, more intentional contract definitions.
And finally, I totally support moving this to GitHub Discussions. Thanks for doing that! I’d love to keep the thread alive and visible for others who might be exploring similar ideas or building similar tooling.

Matt Fellows
Stub != Mock
Mock validates, stub does not

I can't speak for JVM I'm afraid. might be able to provide some pointers, but perhaps the distinction between stubs and mocks might help

Daniel Willian

Hey folks!
Now that we've confirmed this verification process works with a pact file, the potential next step would be to make it work seamlessly by retrieving the pact from the Pact Broker.
At this point, the remaining piece isn't strictly a technical gap, but more of a proposal around how contracts are published and retrieved in the Pact Broker.
Specifically:
I'm exploring the idea of enabling shared or draft contracts, pacts that aren't just produced and verified by consumers and providers independently but are agreed upon collaboratively, versioned intentionally, and uploaded to the broker with that purpose in mind.
These would not follow the usual semantics of:

“Participant A produced a pact, and participant B verified it.”

Instead, these contracts would be:

• Versioned artifacts (e.g., contract-v1.2.0, draft-v1.2.0, agreed-v1.2.0)
• Used by both sides, each binding to a specific version and verifying they adhere to it

Just to clarify: even though both sides are binding to the same contract, they would continue to publish verification results as usual, reporting that they fulfill a pact file.
At this stage, the shared contract and the pact being verified would be the same file, but not formally linked in the Broker’s participant/version graph.
This is just about using the Broker as a source of truth for contract retrieval, nothing more yet.
I believe this model offers a path to true bi-directional testing that really plays to Pact’s strengths:

• Example-based request/response mapping, not just schema validation
• Integration with Pact’s compatibility matrix and can-i-deploy
• A natural extension of existing Pact semantics, not a reinvention

Whereas some directions for bi-directional testing are leaning toward OpenAPI-based schema validation, I believe this approach retains the behavioral confidence Pact is known for while enabling better collaboration across teams.
Of course, I realize this requires a semantic shift in what a "version" means in the Pact Broker, from "a version of a participant's contract" to sometimes "a version of an agreed interface."
So I wanted to ask directly:

"Would this be considered too broad of a change to be supported in the Broker and Pact ecosystem, or is it something that could be explored formally?"

Really appreciate all the feedback and openness so far, and I'm happy to contribute more structured thoughts if there's interest in taking this further.

Thanks again 🙏