Programmatic per-test overrides and request-level verification in microcks-testcontainers-java

[lukaszgyg]

Hi Microcks team,

I attended KubeCon Europe 2026 in Amsterdam and really enjoyed Laurent’s talk. It pushed me to take a closer look at where Microcks could fit even better into the everyday developer testing workflow.

I’d like to raise an idea that I think could be a good fit for microcks-testcontainers-java: first-class support for programmatic per-test overrides of imported mocks, together with request-level verification and inspection.

I’ve seen discussions like #809 around using native Microcks dispatchers to select specific responses. My question is slightly different: whether microcks-testcontainers-java should also offer a test-oriented layer for temporary per-test overrides and fine-grained request verification on top of imported mocks.

The use case is straightforward:

• import an OpenAPI definition into Microcks and use it as the default mock behavior
• for a specific integration test, override one endpoint response programmatically
• verify that requests were actually sent with the expected method/path/query/header/body
• optionally inspect the recorded request payload in assertions

In practice, this means things like:

• return a temporary 503 for one operation in one test
• override a response body for a specific request shape
• apply an override only once, then fall back to the contract-backed mock
• assert that a request was observed, observed n times, or inspect the last recorded request

Conceptually, I see this as complementary to Microcks, not as a replacement for contract-backed mocks. The imported API definition remains the source of truth and baseline behavior. The override layer just helps with narrow test-specific scenarios.

Something along these lines would be very useful:

  client.when(request().withMethod("POST").withPath("/orders"))
        .respond(json(503, "{\"message\":\"temporary failure\"}").times(1));

  client.verify(request().withMethod("POST").withPath("/orders"));
  client.verify(request().withMethod("POST").withPath("/orders"), times(2));

  RecordedRequest last = client.getLastRecordedRequest(
      request().withMethod("POST").withPath("/orders")
  );

The reason I think this matters is that similar tools in this ecosystem, especially MockServer and WireMock-style setups, already provide this kind of capability. That makes them very convenient in day-to-day integration testing, even when they are weaker from a contract-first perspective.

If Microcks had a good story here inside microcks-testcontainers-java, I think it would lower the switching cost and encourage more teams to move from those tools toward a contract-backed workflow instead of staying with pure request/response stubbing tools.

My questions are:

1. Does this sound like a direction that would make sense for the Microcks ecosystem?
2. Do you also see microcks-testcontainers-java as the right home for it?
3. Is there already an intended extension point for this workflow that I may be missing?

Happy to share more details or a concrete API proposal if this sounds interesting.

Regards
Lukasz

[lbroudoux]

Hi Lukasz,

Thanks a lot for taking the time to write this proposal! As you can imagine this is a crazy week for us but I'll take time to thoroughly review and think about your writing.

In the meantime, if you're still at KubeCon you can come and say hi! at the Project Pavilion - we have a kiosk from 10am to 01pm today.

Cheers,