mockserver-client 9.1.0__tar.gz → 9.2.0__tar.gz

{mockserver_client-9.1.0 → mockserver_client-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockserver-client
-Version: 9.1.0
+Version: 9.2.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
@@ -238,6 +238,35 @@ client.when(
 HttpRequest(headers={"keyMatchStyle": "MATCHING_KEY", "X-Tag": ["a", "b"]})
 ```
 
+A value can also be a `DateTimeMatcher`, which matches a header, query or path
+parameter, or cookie holding a date-time before, after or equal to an expected
+value (`now`, `now -1 hours`, or a date-time such as `2026-10-21T00:00:00Z`).
+A plain string such as `"before:2026-01-01"` is always matched literally.
+
+```python
+from mockserver import DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders") \
+    .with_header("X-Issued-At", DateTimeMatcher.after("now -1 hours")) \
+    .with_header("If-Modified-Since", DateTimeMatcher.before("now").with_actual_format("rfc1123")) \
+    .with_cookie("seen", DateTimeMatcher.equal_to_date_time("now").with_truncate_actual("startOfDay"))
+```
+
+Each `with_*` option (`with_actual_format`, `with_truncate_expected`,
+`with_truncate_actual`, `with_apply_truncation_last`, `with_zone`, `with_not`)
+returns a new matcher.
+
+A JSONPath or XPath body matcher can take a `DateTimeMatcher` too: the body
+matches when a value the JSONPath selects, or the text of a node the XPath
+selects, is a matching date-time.
+
+```python
+from mockserver import Body, DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders", body=Body.json_path("$.order.created", DateTimeMatcher.after("now -1 days")))
+HttpRequest(path="/soap", body=Body.xpath("/order/@expires", None, DateTimeMatcher.after("now")))
+```
+
 ### JWT matcher
 
 Match requests by the claims (and metadata) of a JWT carried in a header. Each
@@ -269,6 +298,32 @@ client.when(
 HttpRequest.request("/secure").with_jwt(Jwt(claims={"sub": "user-123"}))
 ```
 
+### Client IP matcher
+
+Match requests by the client IP address or CIDR range, IPv4 or IPv6. The client address is the TCP peer of the connection, not `X-Forwarded-For`; prefix with `!` to match every other address.
+
+```python
+HttpRequest.request("/internal").with_client_ip("10.0.0.0/8")
+# or HttpRequest(path="/internal", client_ip="!10.0.0.0/8")
+```
+
+### Any-of (logical OR) matcher
+
+`AnyOfRequestDefinition` matches a request when any one of its request matchers does, tried in order. Entries may be `HttpRequest`, `OpenAPIDefinition`, `ConditionalRequestDefinition` or a nested `AnyOfRequestDefinition`; `not_any_of=True` matches requests that match none of them. It serialises to `{"anyOf": [...]}` inside `httpRequest`.
+
+```python
+from mockserver import AnyOfRequestDefinition, HttpRequest, HttpResponse
+
+client.when(
+    AnyOfRequestDefinition.request_any_of(
+        HttpRequest(method="GET", path="/pets"),
+        HttpRequest(method="GET", path="/animals"),
+    )
+).respond(HttpResponse(body="pets or animals"))
+```
+
+`ExplainedExpectation.any_of` (an `AnyOfBranchComparison`) says which entry came closest when none matches.
+
 ### allOf body matcher
 
 Require a request body to satisfy **all** of several body matchers at once.
@@ -329,6 +384,40 @@ expectations = client.retrieve_active_expectations()
 logs = client.retrieve_log_messages()
 ```
 
+### Expectation metadata, unmatched expectations and paging
+
+Label expectations with metadata (string keys, any JSON value). Metadata never
+affects matching; it is returned on retrieve and lets you retrieve or clear
+just your own expectations.
+
+```python
+from mockserver import ExpectationFilter, JSON_NULL, RecordedExpectationsOptions
+
+client.when(HttpRequest.request("/api/users")).with_metadata("owner", "team-a").with_metadata(
+    "ticket", 4211
+).respond(HttpResponse(status_code=200))
+
+mine = client.retrieve_active_expectations_by_metadata("owner", "team-a")
+labelled = client.retrieve_active_expectations_by_metadata_key("owner")
+never_matched = client.retrieve_unmatched_expectations()
+page = client.retrieve_active_expectations(
+    expectation_filter=ExpectationFilter().with_metadata_json_path("$.tags[?(@ == 'smoke')]").with_offset(0).with_limit(20)
+)
+recorded_page = client.retrieve_recorded_expectations(offset=0, limit=50)
+# replay changing responses in order, keep only some request headers, move large bodies into files
+shaped = client.retrieve_recorded_expectations(
+    options=RecordedExpectationsOptions().with_repeats_as_scenarios().with_capture_headers("X-Tenant").with_extract_bodies_larger_than(1024)
+)
+
+client.clear_by_metadata("owner", "team-a")      # str compared as text, other values as JSON
+client.clear_by_metadata_key("ticket")           # any value
+client.clear_unmatched_expectations()
+```
+
+These calls raise `ValueError` before sending anything for a blank key or JSONPath,
+a `None` value (use `..._by_metadata_key` for any value, or `JSON_NULL` for a JSON
+null), a negative offset or limit, or a clear whose filter selects nothing or pages.
+
 ## Control
 
 ```python
@@ -474,6 +563,12 @@ client = MockServerClient("localhost", 1080, control_plane_bearer_token=jwt)
 client = MockServerClient("localhost", 1080, control_plane_bearer_token_supplier=fetch_jwt)
 ```
 
+When MockServer accepts control-plane Basic authentication, pass `control_plane_basic_auth=(username, password)` with `secure=True` (MockServer refuses Basic credentials without TLS). They are sent on the same requests and WebSocket; a bearer token, when also set, is sent instead.
+
+```python
+client = MockServerClient("localhost", 1080, secure=True, control_plane_basic_auth=("admin", os.environ["MOCKSERVER_PASSWORD"]))
+```
+
 When MockServer requires mutual TLS for the control plane, pass `client_cert_path` and `client_key_path` (with `secure=True` and, for a private CA, `ca_cert_path`). The client presents that certificate, and trusts that CA, on every control-plane request and on the callback WebSocket.
 
 ```python
@@ -584,7 +679,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="9.1.0")
+server = start(port=1080, version="9.2.0")
 # ...
 server.stop()
 ```

{mockserver_client-9.1.0 → mockserver_client-9.2.0}/README.md

@@ -208,6 +208,35 @@ client.when(
 HttpRequest(headers={"keyMatchStyle": "MATCHING_KEY", "X-Tag": ["a", "b"]})
 ```
 
+A value can also be a `DateTimeMatcher`, which matches a header, query or path
+parameter, or cookie holding a date-time before, after or equal to an expected
+value (`now`, `now -1 hours`, or a date-time such as `2026-10-21T00:00:00Z`).
+A plain string such as `"before:2026-01-01"` is always matched literally.
+
+```python
+from mockserver import DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders") \
+    .with_header("X-Issued-At", DateTimeMatcher.after("now -1 hours")) \
+    .with_header("If-Modified-Since", DateTimeMatcher.before("now").with_actual_format("rfc1123")) \
+    .with_cookie("seen", DateTimeMatcher.equal_to_date_time("now").with_truncate_actual("startOfDay"))
+```
+
+Each `with_*` option (`with_actual_format`, `with_truncate_expected`,
+`with_truncate_actual`, `with_apply_truncation_last`, `with_zone`, `with_not`)
+returns a new matcher.
+
+A JSONPath or XPath body matcher can take a `DateTimeMatcher` too: the body
+matches when a value the JSONPath selects, or the text of a node the XPath
+selects, is a matching date-time.
+
+```python
+from mockserver import Body, DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders", body=Body.json_path("$.order.created", DateTimeMatcher.after("now -1 days")))
+HttpRequest(path="/soap", body=Body.xpath("/order/@expires", None, DateTimeMatcher.after("now")))
+```
+
 ### JWT matcher
 
 Match requests by the claims (and metadata) of a JWT carried in a header. Each
@@ -239,6 +268,32 @@ client.when(
 HttpRequest.request("/secure").with_jwt(Jwt(claims={"sub": "user-123"}))
 ```
 
+### Client IP matcher
+
+Match requests by the client IP address or CIDR range, IPv4 or IPv6. The client address is the TCP peer of the connection, not `X-Forwarded-For`; prefix with `!` to match every other address.
+
+```python
+HttpRequest.request("/internal").with_client_ip("10.0.0.0/8")
+# or HttpRequest(path="/internal", client_ip="!10.0.0.0/8")
+```
+
+### Any-of (logical OR) matcher
+
+`AnyOfRequestDefinition` matches a request when any one of its request matchers does, tried in order. Entries may be `HttpRequest`, `OpenAPIDefinition`, `ConditionalRequestDefinition` or a nested `AnyOfRequestDefinition`; `not_any_of=True` matches requests that match none of them. It serialises to `{"anyOf": [...]}` inside `httpRequest`.
+
+```python
+from mockserver import AnyOfRequestDefinition, HttpRequest, HttpResponse
+
+client.when(
+    AnyOfRequestDefinition.request_any_of(
+        HttpRequest(method="GET", path="/pets"),
+        HttpRequest(method="GET", path="/animals"),
+    )
+).respond(HttpResponse(body="pets or animals"))
+```
+
+`ExplainedExpectation.any_of` (an `AnyOfBranchComparison`) says which entry came closest when none matches.
+
 ### allOf body matcher
 
 Require a request body to satisfy **all** of several body matchers at once.
@@ -299,6 +354,40 @@ expectations = client.retrieve_active_expectations()
 logs = client.retrieve_log_messages()
 ```
 
+### Expectation metadata, unmatched expectations and paging
+
+Label expectations with metadata (string keys, any JSON value). Metadata never
+affects matching; it is returned on retrieve and lets you retrieve or clear
+just your own expectations.
+
+```python
+from mockserver import ExpectationFilter, JSON_NULL, RecordedExpectationsOptions
+
+client.when(HttpRequest.request("/api/users")).with_metadata("owner", "team-a").with_metadata(
+    "ticket", 4211
+).respond(HttpResponse(status_code=200))
+
+mine = client.retrieve_active_expectations_by_metadata("owner", "team-a")
+labelled = client.retrieve_active_expectations_by_metadata_key("owner")
+never_matched = client.retrieve_unmatched_expectations()
+page = client.retrieve_active_expectations(
+    expectation_filter=ExpectationFilter().with_metadata_json_path("$.tags[?(@ == 'smoke')]").with_offset(0).with_limit(20)
+)
+recorded_page = client.retrieve_recorded_expectations(offset=0, limit=50)
+# replay changing responses in order, keep only some request headers, move large bodies into files
+shaped = client.retrieve_recorded_expectations(
+    options=RecordedExpectationsOptions().with_repeats_as_scenarios().with_capture_headers("X-Tenant").with_extract_bodies_larger_than(1024)
+)
+
+client.clear_by_metadata("owner", "team-a")      # str compared as text, other values as JSON
+client.clear_by_metadata_key("ticket")           # any value
+client.clear_unmatched_expectations()
+```
+
+These calls raise `ValueError` before sending anything for a blank key or JSONPath,
+a `None` value (use `..._by_metadata_key` for any value, or `JSON_NULL` for a JSON
+null), a negative offset or limit, or a clear whose filter selects nothing or pages.
+
 ## Control
 
 ```python
@@ -444,6 +533,12 @@ client = MockServerClient("localhost", 1080, control_plane_bearer_token=jwt)
 client = MockServerClient("localhost", 1080, control_plane_bearer_token_supplier=fetch_jwt)
 ```
 
+When MockServer accepts control-plane Basic authentication, pass `control_plane_basic_auth=(username, password)` with `secure=True` (MockServer refuses Basic credentials without TLS). They are sent on the same requests and WebSocket; a bearer token, when also set, is sent instead.
+
+```python
+client = MockServerClient("localhost", 1080, secure=True, control_plane_basic_auth=("admin", os.environ["MOCKSERVER_PASSWORD"]))
+```
+
 When MockServer requires mutual TLS for the control plane, pass `client_cert_path` and `client_key_path` (with `secure=True` and, for a private CA, `ca_cert_path`). The client presents that certificate, and trusts that CA, on every control-plane request and on the callback WebSocket.
 
 ```python
@@ -554,7 +649,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="9.1.0")
+server = start(port=1080, version="9.2.0")
 # ...
 server.stop()
 ```

{mockserver_client-9.1.0 → mockserver_client-9.2.0}/mockserver/__init__.py

@@ -1,6 +1,8 @@
 from mockserver.models import (
     AfterAction,
     AllOfBody,
+    AnyOfBranchComparison,
+    AnyOfRequestDefinition,
     BinaryResponse,
     BinaryUpstream,
     Body,
@@ -8,6 +10,7 @@ from mockserver.models import (
     CaptureSource,
     ConditionalRequestDefinition,
     ConnectionOptions,
+    DateTimeMatcher,
     CrossProtocolScenario,
     CrossProtocolTrigger,
     Delay,
@@ -18,7 +21,10 @@ from mockserver.models import (
     DnsRequestDefinition,
     DnsResponse,
     Expectation,
+    ExpectationFilter,
+    RecordedExpectationsOptions,
     ExpectationId,
+    JSON_NULL,
     ExpectationStep,
     GraphQLBody,
     GraphQLSubscriptionFilter,
@@ -165,6 +171,8 @@ from mockserver.launcher import (
 __all__ = [
     "AfterAction",
     "AllOfBody",
+    "AnyOfBranchComparison",
+    "AnyOfRequestDefinition",
     "AsyncMockServerClient",
     "BinaryResponse",
     "BinaryUpstream",
@@ -173,6 +181,7 @@ __all__ = [
     "CaptureSource",
     "ConditionalRequestDefinition",
     "ConnectionOptions",
+    "DateTimeMatcher",
     "CrossProtocolScenario",
     "CrossProtocolTrigger",
     "Delay",
@@ -183,7 +192,10 @@ __all__ = [
     "DnsRequestDefinition",
     "DnsResponse",
     "Expectation",
+    "ExpectationFilter",
+    "RecordedExpectationsOptions",
     "ExpectationId",
+    "JSON_NULL",
     "ExpectationStep",
     "GraphQLBody",
     "GraphQLSubscriptionFilter",

{mockserver_client-9.1.0 → mockserver_client-9.2.0}/mockserver/async_client.py

@@ -18,10 +18,12 @@ from mockserver.exceptions import (
 )
 from mockserver.fluent import ForwardChainExpectation
 from mockserver.models import (
+    AnyOfRequestDefinition,
     ConditionalRequestDefinition,
     DebugMismatchResult,
     DnsRequestDefinition,
     Expectation,
+    ExpectationFilter,
     ExplainUnmatchedResult,
     HttpChaosProfile,
     HttpObjectCallback,
@@ -31,6 +33,7 @@ from mockserver.models import (
     LoadScenario,
     OpenAPIExpectation,
     Ports,
+    RecordedExpectationsOptions,
     RequestExplanation,
     TimeToLive,
     Times,
@@ -60,6 +63,10 @@ def _log_import_warnings(format: str | None, warnings: object) -> None:
     )
 
 
+# Default for clear()'s expectation_filter: only an omitted argument means "no filter".
+NO_FILTER: Any = object()
+
+
 class AsyncScenarioHandle:
     """An async handle to a single named stateful scenario on the server.
 
@@ -126,6 +133,7 @@ class AsyncMockServerClient:
         client_key_path: str | None = None,
         control_plane_bearer_token: str | None = None,
         control_plane_bearer_token_supplier: Callable[[], str] | None = None,
+        control_plane_basic_auth: tuple[str, str] | None = None,
     ) -> None:
         self._host = host
         self._port = port
@@ -137,6 +145,22 @@ class AsyncMockServerClient:
         self._client_key_path = client_key_path
         self._control_plane_bearer_token = control_plane_bearer_token
         self._control_plane_bearer_token_supplier = control_plane_bearer_token_supplier
+        self._control_plane_basic_authorization: str | None = None
+        if control_plane_basic_auth is not None:
+            username, password = control_plane_basic_auth
+            if not username or ":" in username or password is None:
+                raise ValueError(
+                    "control_plane_basic_auth needs a (username, password) with a username without ':'"
+                )
+            self._control_plane_basic_authorization = "Basic " + base64.b64encode(
+                f"{username}:{password}".encode("utf-8")
+            ).decode("ascii")
+            if not secure:
+                logger.warning(
+                    "control-plane Basic credentials are configured without secure=True, so the password can be "
+                    "read on the network, and MockServer refuses them unless "
+                    "controlPlaneBasicAuthenticationAllowInsecure is set (tests only)"
+                )
         self._websocket_clients: list[MockServerWebSocketClient] = []
 
         scheme = "https" if secure else "http"
@@ -169,6 +193,16 @@ class AsyncMockServerClient:
             return self._control_plane_bearer_token_supplier()
         return self._control_plane_bearer_token
 
+    def _control_plane_authorization(self) -> str | None:
+        """The control-plane ``Authorization`` header value: the bearer token
+        when one is configured, else the Basic credentials, else ``None``.
+        MockServer refuses Basic credentials without TLS, so use ``secure=True``.
+        """
+        bearer = self._control_plane_bearer()
+        if bearer:
+            return f"Bearer {bearer}"
+        return self._control_plane_basic_authorization
+
     async def _request(
         self,
         method: str,
@@ -189,9 +223,9 @@ class AsyncMockServerClient:
             data = None
         req = urllib.request.Request(url, data=data, method=method)
         req.add_header("Content-Type", content_type)
-        bearer = self._control_plane_bearer()
-        if bearer:
-            req.add_header("Authorization", f"Bearer {bearer}")
+        authorization = self._control_plane_authorization()
+        if authorization:
+            req.add_header("Authorization", authorization)
 
         def _do_request() -> tuple[int, str]:
             try:
@@ -242,7 +276,21 @@ class AsyncMockServerClient:
         self,
         request: HttpRequest | None = None,
         clear_type: str | None = None,
+        expectation_filter: ExpectationFilter = NO_FILTER,  # type: ignore[assignment]
     ) -> None:
+        """Clear state matching ``request`` (everything when omitted).
+
+        With ``expectation_filter``, only the expectations that match both the
+        request and the filter's metadata or unmatched selection are cleared and
+        the event log is left untouched. A filter that selects nothing, that pages,
+        or a ``clear_type`` other than ``expectations`` raises ``ValueError``
+        before anything is sent. Passing ``expectation_filter=None`` explicitly
+        raises too: only omitting it means a clear without a filter.
+        """
+        if expectation_filter is not NO_FILTER:
+            # fail closed: an explicit None (e.g. from a helper that returned nothing) must not
+            # become a clear of every expectation and the whole log
+            return await self._clear_with_filter(request, clear_type, expectation_filter)
         query_params = {}
         if clear_type:
             query_params["type"] = clear_type
@@ -255,6 +303,53 @@ class AsyncMockServerClient:
                 f"Failed to clear (status={status}): {response_body}"
             )
 
+    async def _clear_with_filter(
+        self,
+        request: HttpRequest | None,
+        clear_type: str | None,
+        expectation_filter: ExpectationFilter,
+    ) -> None:
+        # fail closed: a filter that selects nothing would otherwise clear every expectation
+        if not isinstance(expectation_filter, ExpectationFilter):
+            raise ValueError("expectation_filter must be an ExpectationFilter")
+        if not expectation_filter.has_selection():
+            raise ValueError(
+                "clear with a filter requires a metadata or unmatched selection; "
+                "use clear(request) to clear without one"
+            )
+        if expectation_filter.has_paging():
+            raise ValueError("offset and limit are not supported for clear")
+        if clear_type is not None and clear_type.lower() != "expectations":
+            raise ValueError(
+                f"clear with a filter only clears expectations, not clear_type={clear_type!r}"
+            )
+        query_params = {"type": "expectations"}
+        query_params.update(expectation_filter.to_query_params())
+        body = json.dumps(request.to_dict()) if request else ""
+        status, response_body = await self._request(
+            "PUT", "/mockserver/clear", body, query_params
+        )
+        if status >= 400:
+            raise MockServerError(
+                f"Failed to clear (status={status}): {response_body}"
+            )
+
+    async def clear_by_metadata(self, key: str, value: Any) -> None:
+        """Clear the expectations whose metadata has ``key`` with a value equal to ``value``.
+
+        ``value`` must not be ``None``: use :meth:`clear_by_metadata_key` for any
+        value, or ``JSON_NULL`` for a JSON null.
+        """
+        await self.clear(expectation_filter=ExpectationFilter().with_metadata(key, value))
+
+    async def clear_by_metadata_key(self, key: str) -> None:
+        """Clear the expectations whose metadata has ``key``, whatever its value."""
+        await self.clear(expectation_filter=ExpectationFilter().with_metadata_key(key))
+
+    async def clear_unmatched_expectations(self) -> None:
+        """Clear the expectations that have not matched any request."""
+        await self.clear(expectation_filter=ExpectationFilter().with_unmatched(True))
+
     async def clear_by_id(
         self,
         expectation_id: str,
@@ -393,7 +488,9 @@ class AsyncMockServerClient:
         Issues ``PUT /mockserver/configuration`` with *config_json* (a
         ``ConfigurationDTO`` JSON document; only the present fields are applied)
         and returns the serialized updated configuration JSON. A ``None`` body is
-        sent as an empty string.
+        sent as an empty string. Properties fixed at startup, such as
+        ``forwardProxyBlockPrivateNetworks``, ``forwardProxyAllowedHosts`` and
+        ``forwardProxyDeniedHosts``, are ignored and the server logs a warning.
         """
         body = config_json if config_json is not None else ""
         status, response_body = await self._request(
@@ -1165,7 +1262,7 @@ class AsyncMockServerClient:
 
     async def verify(
         self,
-        request: HttpRequest | ConditionalRequestDefinition | None = None,
+        request: HttpRequest | ConditionalRequestDefinition | AnyOfRequestDefinition | None = None,
         times: VerificationTimes | None = None,
         *,
         response: HttpResponse | None = None,
@@ -1182,7 +1279,7 @@ class AsyncMockServerClient:
 
     async def verify_sequence(
         self,
-        *requests: HttpRequest | ConditionalRequestDefinition,
+        *requests: HttpRequest | ConditionalRequestDefinition | AnyOfRequestDefinition,
         responses: list[HttpResponse] | None = None,
     ) -> None:
         verification = VerificationSequence(
@@ -1231,14 +1328,23 @@ class AsyncMockServerClient:
         return []
 
     async def retrieve_active_expectations(
-        self, request: HttpRequest | None = None
+        self,
+        request: HttpRequest | None = None,
+        expectation_filter: ExpectationFilter | None = None,
     ) -> list[Expectation]:
+        """Retrieve the active expectations matching ``request`` (all when omitted)
+        and, when given, ``expectation_filter`` (metadata, unmatched, offset, limit)."""
+        query_params = {"type": "ACTIVE_EXPECTATIONS", "format": "JSON"}
+        if expectation_filter is not None:
+            if not isinstance(expectation_filter, ExpectationFilter):
+                raise ValueError("expectation_filter must be an ExpectationFilter")
+            query_params.update(expectation_filter.to_query_params())
         body = json.dumps(request.to_dict()) if request else ""
         status, response_body = await self._request(
             "PUT",
             "/mockserver/retrieve",
             body,
-            {"type": "ACTIVE_EXPECTATIONS", "format": "JSON"},
+            query_params,
         )
         if status >= 400:
             raise MockServerError(
@@ -1250,15 +1356,56 @@ class AsyncMockServerClient:
                 return [Expectation.from_dict(e) for e in parsed]
         return []
 
+    async def retrieve_active_expectations_by_metadata(
+        self, key: str, value: Any
+    ) -> list[Expectation]:
+        """Retrieve the active expectations whose metadata has ``key`` with a value
+        equal to ``value``: a ``str`` is compared as text, any other value as JSON."""
+        return await self.retrieve_active_expectations(
+            None, ExpectationFilter().with_metadata(key, value)
+        )
+
+    async def retrieve_active_expectations_by_metadata_key(
+        self, key: str
+    ) -> list[Expectation]:
+        """Retrieve the active expectations whose metadata has ``key``, whatever its value."""
+        return await self.retrieve_active_expectations(
+            None, ExpectationFilter().with_metadata_key(key)
+        )
+
+    async def retrieve_unmatched_expectations(self) -> list[Expectation]:
+        """Retrieve the active expectations that have not matched any request."""
+        return await self.retrieve_active_expectations(
+            None, ExpectationFilter().with_unmatched(True)
+        )
+
     async def retrieve_recorded_expectations(
-        self, request: HttpRequest | None = None
+        self,
+        request: HttpRequest | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+        options: RecordedExpectationsOptions | None = None,
     ) -> list[Expectation]:
+        """Retrieve the recorded expectations matching ``request`` (all when omitted),
+        optionally one page of them, in the order the requests were received.
+
+        ``options`` shapes the returned expectations, for example replaying a request
+        recorded with different responses in order (see :class:`RecordedExpectationsOptions`).
+        """
+        if options is not None and not isinstance(options, RecordedExpectationsOptions):
+            raise ValueError(f"options must be a RecordedExpectationsOptions, got {options!r}")
+        query_params = {"type": "RECORDED_EXPECTATIONS", "format": "JSON"}
+        if options is not None:
+            query_params.update(options.to_query_params())
+        query_params.update(
+            ExpectationFilter().with_offset(offset).with_limit(limit).to_query_params()
+        )
         body = json.dumps(request.to_dict()) if request else ""
         status, response_body = await self._request(
             "PUT",
             "/mockserver/retrieve",
             body,
-            {"type": "RECORDED_EXPECTATIONS", "format": "JSON"},
+            query_params,
         )
         if status >= 400:
             raise MockServerError(
@@ -1558,7 +1705,7 @@ class AsyncMockServerClient:
 
     def when(
         self,
-        request: HttpRequest | ConditionalRequestDefinition,
+        request: HttpRequest | ConditionalRequestDefinition | AnyOfRequestDefinition,
         times: Times | None = None,
         time_to_live: TimeToLive | None = None,
         priority: int | None = None,
@@ -1637,7 +1784,7 @@ class AsyncMockServerClient:
                 self._secure,
                 self._ca_cert_path,
                 tls_verify=self._tls_verify,
-                bearer_token_supplier=self._control_plane_bearer,
+                authorization_supplier=self._control_plane_authorization,
                 ssl_context=self._ssl_context,
             )
             ws_client._is_breakpoint_ws = True  # type: ignore[attr-defined]
@@ -1799,7 +1946,7 @@ class AsyncMockServerClient:
             self._secure,
             self._ca_cert_path,
             tls_verify=self._tls_verify,
-            bearer_token_supplier=self._control_plane_bearer,
+            authorization_supplier=self._control_plane_authorization,
             ssl_context=self._ssl_context,
         )