mockserver-client 7.6.0__tar.gz → 9.0.0__tar.gz

{mockserver_client-7.6.0 → mockserver_client-9.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockserver-client
-Version: 7.6.0
+Version: 9.0.0
 Summary: Official Python client for MockServer — create expectations, verify requests, and register dynamic callbacks via WebSocket
 Author-email: James Bloom <jamesdbloom@gmail.com>
 License-Expression: Apache-2.0
@@ -162,6 +162,27 @@ client.mock_with_forward_callback(
 )
 ```
 
+## Forward with Overrides
+
+Forward the matched request with fields replaced (`request_override`), modified
+(`request_modifier`), or with its response overridden (`response_override`,
+`response_modifier`, `response_template`), without a callback:
+
+```python
+from mockserver import HttpOverrideForwardedRequest, HttpRequest, HttpResponse
+
+client.when(HttpRequest.request("/some/path")).forward(
+    HttpOverrideForwardedRequest(
+        request_override=HttpRequest(path="/other/path", headers={"Host": ["target.host.com"]}),
+        response_override=HttpResponse(headers={"X-Proxied": ["true"]}),
+        response_modifier={"headers": {"remove": ["Server"]}},
+    )
+)
+```
+
+`http_request` and `http_response` are deprecated aliases of `request_override`
+and `response_override`, kept for existing code; set one name of each pair, not both.
+
 ## Verification
 
 ```python
@@ -192,6 +213,31 @@ client.verify_zero_interactions()
 
 ## Request Matching
 
+### Headers, query parameters and cookies
+
+Pass headers, query and path parameters, trailers and cookies as a dict, as in
+MockServer's JSON, or as a list of `KeyToMultiValue`. A `"keyMatchStyle"` key
+(`SUB_SET`, the default, or `MATCHING_KEY`) sets how the values of a key are
+matched.
+
+```python
+from mockserver import HttpRequest, HttpResponse
+
+client.when(
+    HttpRequest(
+        path="/search",
+        headers={"Accept": "application/json"},        # one value
+        query_string_parameters={"tag": ["a", "b"]},   # several values
+        cookies={"session": "abc"},
+    )
+).respond(
+    HttpResponse(status_code=302, headers={"Location": ["https://example.com"]})
+)
+
+# every value the request has for X-Tag must match, not just one
+HttpRequest(headers={"keyMatchStyle": "MATCHING_KEY", "X-Tag": ["a", "b"]})
+```
+
 ### JWT matcher
 
 Match requests by the claims (and metadata) of a JWT carried in a header. Each
@@ -247,6 +293,27 @@ HttpRequest.request("/api/orders").with_body(
 )
 ```
 
+### Conditional (if/then/else) matcher
+
+Pass a `ConditionalRequestDefinition` where a request matcher goes: when
+`if_request` matches, `then_request` must match too; otherwise `else_request`
+must (with no `else_request` it matches whenever `if_request` does not). Each
+branch is an `HttpRequest`, an `OpenAPIDefinition` or another
+`ConditionalRequestDefinition`. Retrieved expectations whose `httpRequest` holds
+`if` read back as this type.
+
+```python
+from mockserver import Body, ConditionalRequestDefinition, HttpRequest, HttpResponse
+
+client.when(
+    ConditionalRequestDefinition(
+        if_request=HttpRequest(method="POST").with_header("content-type", "application/json"),
+        then_request=HttpRequest(body=Body.json_schema('{"type": "object", "required": ["orderId"]}')),
+        else_request=HttpRequest(method="GET"),
+    )
+).respond(HttpResponse(status_code=200))
+```
+
 ## Retrieval
 
 ```python
@@ -362,6 +429,21 @@ client.start_chaos_experiment({
 Both methods are available on the async client too (`await client.verify_slo(...)`,
 `await client.start_chaos_experiment(...)`).
 
+## Diagnose Matching
+
+`explain(correlation_id)` tells you which expectation would serve a recorded request now and why
+each expectation ahead of it was passed over; `debug_mismatch(request)` compares a request with
+every active expectation; `explain_unmatched(limit=..., suggest_fixes=...)` explains recent
+requests that matched nothing. Each returns a typed dataclass (`RequestExplanation`,
+`DebugMismatchResult`, `ExplainUnmatchedResult`) and raises `MockServerError` with the server's
+reason on failure. The async client has the same methods.
+
+```python
+explanation = client.explain("abc-123-def-456")
+for skipped in explanation.skipped_expectations:
+    print(skipped.expectation_id, skipped.reason, skipped.explanation)
+```
+
 ## TLS Support
 
 ```python
@@ -486,7 +568,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="7.6.0")
+server = start(port=1080, version="9.0.0")
 # ...
 server.stop()
 ```
@@ -499,6 +581,8 @@ server.stop()
 | `start(port, version=None, *, extra_args=None, log=True)` | Ensure the binary and start MockServer. Returns a `MockServerProcess`. |
 | `MockServerProcess` | Handle to the running process. Properties: `port`, `pid`, `launcher`, `returncode`. Methods: `stop(timeout=10.0)`. Supports `with` statement. |
 
+On Windows the launcher runs `mockserver.bat` through `cmd.exe` with every argument quoted, so characters such as `&`, `|` and `^` reach MockServer unchanged. `start()` raises `ValueError` if the launcher path or an `extra_args` entry contains a double quote, a line break or NUL, or if together they contain more than one `%` (which `cmd.exe` would expand as a `%NAME%` variable). No shell is used on Linux or macOS.
+
 ### Supported platforms
 
 | OS | Architecture |

{mockserver_client-7.6.0 → mockserver_client-9.0.0}/README.md

@@ -132,6 +132,27 @@ client.mock_with_forward_callback(
 )
 ```
 
+## Forward with Overrides
+
+Forward the matched request with fields replaced (`request_override`), modified
+(`request_modifier`), or with its response overridden (`response_override`,
+`response_modifier`, `response_template`), without a callback:
+
+```python
+from mockserver import HttpOverrideForwardedRequest, HttpRequest, HttpResponse
+
+client.when(HttpRequest.request("/some/path")).forward(
+    HttpOverrideForwardedRequest(
+        request_override=HttpRequest(path="/other/path", headers={"Host": ["target.host.com"]}),
+        response_override=HttpResponse(headers={"X-Proxied": ["true"]}),
+        response_modifier={"headers": {"remove": ["Server"]}},
+    )
+)
+```
+
+`http_request` and `http_response` are deprecated aliases of `request_override`
+and `response_override`, kept for existing code; set one name of each pair, not both.
+
 ## Verification
 
 ```python
@@ -162,6 +183,31 @@ client.verify_zero_interactions()
 
 ## Request Matching
 
+### Headers, query parameters and cookies
+
+Pass headers, query and path parameters, trailers and cookies as a dict, as in
+MockServer's JSON, or as a list of `KeyToMultiValue`. A `"keyMatchStyle"` key
+(`SUB_SET`, the default, or `MATCHING_KEY`) sets how the values of a key are
+matched.
+
+```python
+from mockserver import HttpRequest, HttpResponse
+
+client.when(
+    HttpRequest(
+        path="/search",
+        headers={"Accept": "application/json"},        # one value
+        query_string_parameters={"tag": ["a", "b"]},   # several values
+        cookies={"session": "abc"},
+    )
+).respond(
+    HttpResponse(status_code=302, headers={"Location": ["https://example.com"]})
+)
+
+# every value the request has for X-Tag must match, not just one
+HttpRequest(headers={"keyMatchStyle": "MATCHING_KEY", "X-Tag": ["a", "b"]})
+```
+
 ### JWT matcher
 
 Match requests by the claims (and metadata) of a JWT carried in a header. Each
@@ -217,6 +263,27 @@ HttpRequest.request("/api/orders").with_body(
 )
 ```
 
+### Conditional (if/then/else) matcher
+
+Pass a `ConditionalRequestDefinition` where a request matcher goes: when
+`if_request` matches, `then_request` must match too; otherwise `else_request`
+must (with no `else_request` it matches whenever `if_request` does not). Each
+branch is an `HttpRequest`, an `OpenAPIDefinition` or another
+`ConditionalRequestDefinition`. Retrieved expectations whose `httpRequest` holds
+`if` read back as this type.
+
+```python
+from mockserver import Body, ConditionalRequestDefinition, HttpRequest, HttpResponse
+
+client.when(
+    ConditionalRequestDefinition(
+        if_request=HttpRequest(method="POST").with_header("content-type", "application/json"),
+        then_request=HttpRequest(body=Body.json_schema('{"type": "object", "required": ["orderId"]}')),
+        else_request=HttpRequest(method="GET"),
+    )
+).respond(HttpResponse(status_code=200))
+```
+
 ## Retrieval
 
 ```python
@@ -332,6 +399,21 @@ client.start_chaos_experiment({
 Both methods are available on the async client too (`await client.verify_slo(...)`,
 `await client.start_chaos_experiment(...)`).
 
+## Diagnose Matching
+
+`explain(correlation_id)` tells you which expectation would serve a recorded request now and why
+each expectation ahead of it was passed over; `debug_mismatch(request)` compares a request with
+every active expectation; `explain_unmatched(limit=..., suggest_fixes=...)` explains recent
+requests that matched nothing. Each returns a typed dataclass (`RequestExplanation`,
+`DebugMismatchResult`, `ExplainUnmatchedResult`) and raises `MockServerError` with the server's
+reason on failure. The async client has the same methods.
+
+```python
+explanation = client.explain("abc-123-def-456")
+for skipped in explanation.skipped_expectations:
+    print(skipped.expectation_id, skipped.reason, skipped.explanation)
+```
+
 ## TLS Support
 
 ```python
@@ -456,7 +538,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="7.6.0")
+server = start(port=1080, version="9.0.0")
 # ...
 server.stop()
 ```
@@ -469,6 +551,8 @@ server.stop()
 | `start(port, version=None, *, extra_args=None, log=True)` | Ensure the binary and start MockServer. Returns a `MockServerProcess`. |
 | `MockServerProcess` | Handle to the running process. Properties: `port`, `pid`, `launcher`, `returncode`. Methods: `stop(timeout=10.0)`. Supports `with` statement. |
 
+On Windows the launcher runs `mockserver.bat` through `cmd.exe` with every argument quoted, so characters such as `&`, `|` and `^` reach MockServer unchanged. `start()` raises `ValueError` if the launcher path or an `extra_args` entry contains a double quote, a line break or NUL, or if together they contain more than one `%` (which `cmd.exe` would expand as a `%NAME%` variable). No shell is used on Linux or macOS.
+
 ### Supported platforms
 
 | OS | Architecture |

{mockserver_client-7.6.0 → mockserver_client-9.0.0}/mockserver/__init__.py

@@ -2,9 +2,11 @@ from mockserver.models import (
     AfterAction,
     AllOfBody,
     BinaryResponse,
+    BinaryUpstream,
     Body,
     CaptureRule,
     CaptureSource,
+    ConditionalRequestDefinition,
     ConnectionOptions,
     CrossProtocolScenario,
     CrossProtocolTrigger,
@@ -19,6 +21,7 @@ from mockserver.models import (
     ExpectationId,
     ExpectationStep,
     GraphQLBody,
+    GraphQLSubscriptionFilter,
     GrpcBidiResponse,
     GrpcBidiRule,
     GrpcStreamMessage,
@@ -47,12 +50,14 @@ from mockserver.models import (
     Protocol,
     RateLimit,
     RateLimitAlgorithm,
+    RecoverAfter,
     ValidationMode,
     WasmBody,
     XmlBody,
     XmlSchemaBody,
     XPathBody,
     LoadCapture,
+    LoadCheck,
     LoadFeeder,
     LoadPacing,
     LoadProfile,
@@ -77,6 +82,17 @@ from mockserver.models import (
     VerificationTimes,
     WebSocketFrameMatcher,
     WebSocketMessage,
+    Arrival,
+    ArrivalForwardFailure,
+    ClosestMatch,
+    DebugMismatchResult,
+    ExplainedExpectation,
+    ExplainedRequest,
+    ExplainUnmatchedResult,
+    ExplanationNarration,
+    RequestExplanation,
+    SuggestedFix,
+    UnmatchedRequest,
 )
 from mockserver.llm import (
     Completion,
@@ -151,9 +167,11 @@ __all__ = [
     "AllOfBody",
     "AsyncMockServerClient",
     "BinaryResponse",
+    "BinaryUpstream",
     "Body",
     "CaptureRule",
     "CaptureSource",
+    "ConditionalRequestDefinition",
     "ConnectionOptions",
     "CrossProtocolScenario",
     "CrossProtocolTrigger",
@@ -168,6 +186,7 @@ __all__ = [
     "ExpectationId",
     "ExpectationStep",
     "GraphQLBody",
+    "GraphQLSubscriptionFilter",
     "GrpcBidiResponse",
     "GrpcBidiRule",
     "GrpcStreamMessage",
@@ -196,12 +215,14 @@ __all__ = [
     "Protocol",
     "RateLimit",
     "RateLimitAlgorithm",
+    "RecoverAfter",
     "ValidationMode",
     "WasmBody",
     "XmlBody",
     "XmlSchemaBody",
     "XPathBody",
     "LoadCapture",
+    "LoadCheck",
     "LoadFeeder",
     "LoadPacing",
     "LoadProfile",
@@ -276,6 +297,17 @@ __all__ = [
     "VerificationTimes",
     "WebSocketFrameMatcher",
     "WebSocketMessage",
+    "Arrival",
+    "ArrivalForwardFailure",
+    "ClosestMatch",
+    "DebugMismatchResult",
+    "ExplainedExpectation",
+    "ExplainedRequest",
+    "ExplainUnmatchedResult",
+    "ExplanationNarration",
+    "RequestExplanation",
+    "SuggestedFix",
+    "UnmatchedRequest",
     "MockServerProcess",
     "bundle_base_name",
     "cache_dir",

{mockserver_client-7.6.0 → mockserver_client-9.0.0}/mockserver/a2a.py

@@ -428,7 +428,7 @@ class A2aMockBuilder:
         return Expectation(
             http_request=self._json_rpc_request("tasks/send"),
             http_override_forwarded_request=HttpOverrideForwardedRequest(
-                http_request=webhook_request,
+                request_override=webhook_request,
                 response_template=client_response_template,
             ),
         )

{mockserver_client-7.6.0 → mockserver_client-9.0.0}/mockserver/async_client.py

@@ -18,7 +18,11 @@ from mockserver.exceptions import (
 )
 from mockserver.fluent import ForwardChainExpectation
 from mockserver.models import (
+    ConditionalRequestDefinition,
+    DebugMismatchResult,
+    DnsRequestDefinition,
     Expectation,
+    ExplainUnmatchedResult,
     HttpChaosProfile,
     HttpObjectCallback,
     HttpRequest,
@@ -27,11 +31,13 @@ from mockserver.models import (
     LoadScenario,
     OpenAPIExpectation,
     Ports,
+    RequestExplanation,
     TimeToLive,
     Times,
     Verification,
     VerificationSequence,
     VerificationTimes,
+    _deserialize_recorded_request,
 )
 from mockserver.websocket_client import MockServerWebSocketClient
 
@@ -757,18 +763,21 @@ class AsyncMockServerClient:
         Returns the verdict dict with a ``result`` of ``PASS`` or ``INCONCLUSIVE``
         (HTTP 200). A ``FAIL`` verdict (HTTP 406) raises
         :class:`MockServerVerificationError` so a CI or chaos gate can assert on it
-        directly. SLO tracking is off by default — the server returns 400 (raised as
-        :class:`MockServerError`) until started with ``sloTrackingEnabled=true``.
+        directly. SLO tracking is off by default — the server returns 403 (raised as
+        :class:`MockServerError`) until started with ``sloTrackingEnabled=true``;
+        malformed criteria are a separate 400.
         """
         body = json.dumps(criteria)
         status, response_body = await self._request("PUT", "/mockserver/verifySLO", body)
         if status == 406:
             raise MockServerVerificationError(response_body or "SLO verdict: FAIL")
-        if status == 400:
+        if status == 403:
             raise MockServerError(
-                "Invalid SLO criteria (or SLO tracking disabled — set "
-                f"sloTrackingEnabled=true): {response_body}"
+                "SLO tracking is disabled — start MockServer with "
+                f"sloTrackingEnabled=true: {response_body}"
             )
+        if status == 400:
+            raise MockServerError(f"Invalid SLO criteria: {response_body}")
         if status >= 400:
             raise MockServerError(
                 f"Failed to verify SLO (status={status}): {response_body}"
@@ -1114,7 +1123,7 @@ class AsyncMockServerClient:
 
     async def verify(
         self,
-        request: HttpRequest | None = None,
+        request: HttpRequest | ConditionalRequestDefinition | None = None,
         times: VerificationTimes | None = None,
         *,
         response: HttpResponse | None = None,
@@ -1131,7 +1140,7 @@ class AsyncMockServerClient:
 
     async def verify_sequence(
         self,
-        *requests: HttpRequest,
+        *requests: HttpRequest | ConditionalRequestDefinition,
         responses: list[HttpResponse] | None = None,
     ) -> None:
         verification = VerificationSequence(
@@ -1156,8 +1165,12 @@ class AsyncMockServerClient:
         )
 
     async def retrieve_recorded_requests(
-        self, request: HttpRequest | None = None
-    ) -> list[HttpRequest]:
+        self, request: HttpRequest | DnsRequestDefinition | None = None
+    ) -> list[HttpRequest | DnsRequestDefinition | dict]:
+        """Retrieve the recorded requests matching ``request`` (all HTTP requests when
+        omitted). With a DNS filter the DNS queries come back as
+        :class:`DnsRequestDefinition`; a binary message comes back as its raw dict.
+        """
         body = json.dumps(request.to_dict()) if request else ""
         status, response_body = await self._request(
             "PUT",
@@ -1172,7 +1185,7 @@ class AsyncMockServerClient:
         if response_body:
             parsed = json.loads(response_body)
             if isinstance(parsed, list):
-                return [HttpRequest.from_dict(r) for r in parsed]
+                return [_deserialize_recorded_request(r) for r in parsed]
         return []
 
     async def retrieve_active_expectations(
@@ -1215,6 +1228,176 @@ class AsyncMockServerClient:
                 return [Expectation.from_dict(e) for e in parsed]
         return []
 
+    async def _retrieve_by_id(
+        self, expectation_id: str, query_params: dict[str, str]
+    ) -> tuple[int, str]:
+        """Send a retrieve request filtered by expectation id.
+
+        An expectation id may be sent in place of a request matcher. For
+        ``ACTIVE_EXPECTATIONS`` the server returns only the expectation with that
+        id; for every other type it returns the entries matching that
+        expectation's request, exactly as verify by expectation id matches them.
+        An unknown id is rejected with a 400.
+        """
+        return await self._request(
+            "PUT",
+            "/mockserver/retrieve",
+            json.dumps({"id": expectation_id}),
+            query_params,
+        )
+
+    async def retrieve_recorded_requests_by_id(
+        self, expectation_id: str
+    ) -> list[HttpRequest | DnsRequestDefinition | dict]:
+        status, response_body = await self._retrieve_by_id(
+            expectation_id, {"type": "REQUESTS", "format": "JSON"}
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve recorded requests by id (status={status}): {response_body}"
+            )
+        if response_body:
+            parsed = json.loads(response_body)
+            if isinstance(parsed, list):
+                return [_deserialize_recorded_request(r) for r in parsed]
+        return []
+
+    async def retrieve_active_expectations_by_id(
+        self, expectation_id: str
+    ) -> list[Expectation]:
+        status, response_body = await self._retrieve_by_id(
+            expectation_id, {"type": "ACTIVE_EXPECTATIONS", "format": "JSON"}
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve active expectations by id (status={status}): {response_body}"
+            )
+        if response_body:
+            parsed = json.loads(response_body)
+            if isinstance(parsed, list):
+                return [Expectation.from_dict(e) for e in parsed]
+        return []
+
+    async def retrieve_recorded_expectations_by_id(
+        self, expectation_id: str
+    ) -> list[Expectation]:
+        status, response_body = await self._retrieve_by_id(
+            expectation_id, {"type": "RECORDED_EXPECTATIONS", "format": "JSON"}
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve recorded expectations by id (status={status}): {response_body}"
+            )
+        if response_body:
+            parsed = json.loads(response_body)
+            if isinstance(parsed, list):
+                return [Expectation.from_dict(e) for e in parsed]
+        return []
+
+    async def retrieve_recorded_requests_and_responses_by_id(
+        self, expectation_id: str
+    ) -> list[HttpRequestAndHttpResponse]:
+        status, response_body = await self._retrieve_by_id(
+            expectation_id, {"type": "REQUEST_RESPONSES", "format": "JSON"}
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve request/responses by id (status={status}): {response_body}"
+            )
+        if response_body:
+            parsed = json.loads(response_body)
+            if isinstance(parsed, list):
+                return [HttpRequestAndHttpResponse.from_dict(rr) for rr in parsed]
+        return []
+
+    async def retrieve_log_messages_by_id(self, expectation_id: str) -> list[str]:
+        status, response_body = await self._retrieve_by_id(
+            expectation_id, {"type": "LOGS"}
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to retrieve log messages by id (status={status}): {response_body}"
+            )
+        if response_body:
+            try:
+                parsed = json.loads(response_body)
+                if isinstance(parsed, list):
+                    return parsed
+            except json.JSONDecodeError:
+                return response_body.split("------------------------------------\n")
+        return []
+
+    async def _diagnostic(
+        self, path: str, body: str | None, query_params: dict[str, str] | None, failure: str
+    ) -> dict:
+        status, response_body = await self._request("PUT", path, body, query_params)
+        try:
+            parsed = json.loads(response_body) if response_body else {}
+        except json.JSONDecodeError:
+            parsed = None
+        if status != 200 or not isinstance(parsed, dict):
+            reason = parsed.get("error") if isinstance(parsed, dict) else None
+            raise MockServerError(f"{failure} (status={status}): {reason or response_body}")
+        return parsed
+
+    async def explain(self, correlation_id: str) -> RequestExplanation:
+        """Explain how a recorded request would be served now.
+
+        Issues ``PUT /mockserver/explain?correlationId=<id>``, which re-checks the
+        request with that correlation id against the current expectations, in the
+        order MockServer evaluates them, and returns the expectation that would
+        serve it, why each expectation ahead of it was passed over, and which
+        lower-priority expectations it shadows. Read-only: it consumes no Times
+        and moves no scenario.
+
+        Raises :class:`ValueError` for a blank id, and :class:`MockServerError`
+        with the server's reason when no request is recorded with this id (never
+        received, cleared or evicted) or it is not an HTTP request.
+        """
+        if not correlation_id or not correlation_id.strip():
+            raise ValueError("explain requires a non blank correlation_id")
+        data = await self._diagnostic(
+            "/mockserver/explain", None, {"correlationId": correlation_id},
+            f'explain failed for correlationId "{correlation_id}"',
+        )
+        return RequestExplanation.from_dict(data)
+
+    async def debug_mismatch(self, request: HttpRequest | dict) -> DebugMismatchResult:
+        """Compare a request with every active expectation.
+
+        Issues ``PUT /mockserver/debugMismatch`` and returns, for each expectation,
+        whether it matches and the per-field differences, plus the closest match.
+        Only an HTTP request is supported; any other definition raises
+        :class:`MockServerError`.
+        """
+        payload = request.to_dict() if hasattr(request, "to_dict") else request
+        data = await self._diagnostic(
+            "/mockserver/debugMismatch", json.dumps(payload), None, "debugMismatch failed"
+        )
+        return DebugMismatchResult.from_dict(data)
+
+    async def explain_unmatched(
+        self, limit: int | None = None, suggest_fixes: bool | None = None
+    ) -> ExplainUnmatchedResult:
+        """Explain why recent requests matched no expectation.
+
+        Issues ``PUT /mockserver/explainUnmatched`` and returns each recent
+        unmatched request with its closest expectations, closest first. ``limit``
+        bounds how many requests are analysed (server default 10);
+        ``suggest_fixes`` adds a suggested JSON patch to each of the five closest
+        non-matching expectations (nothing is applied).
+        """
+        options: dict[str, Any] = {}
+        if limit is not None:
+            options["limit"] = limit
+        if suggest_fixes is not None:
+            options["suggestFixes"] = suggest_fixes
+        data = await self._diagnostic(
+            "/mockserver/explainUnmatched", json.dumps(options) if options else None, None,
+            "explainUnmatched failed",
+        )
+        return ExplainUnmatchedResult.from_dict(data)
+
     async def retrieve_expectations_as_code(
         self, fmt: str = "java", request: HttpRequest | None = None
     ) -> str:
@@ -1333,7 +1516,7 @@ class AsyncMockServerClient:
 
     def when(
         self,
-        request: HttpRequest,
+        request: HttpRequest | ConditionalRequestDefinition,
         times: Times | None = None,
         time_to_live: TimeToLive | None = None,
         priority: int | None = None,