Struct MockServerClient 

pub struct MockServerClient { /* private fields */ }

A blocking client for the MockServer control-plane REST API.

Created via ClientBuilder. All methods are synchronous.

Implementations

impl MockServerClient

pub fn upsert(&self, expectations: &[Expectation]) -> Result<Vec<Expectation>>

Create one or more expectations on the server.

Returns the created expectations as echoed by the server.

pub fn upsert_raw(&self, expectations: Value) -> Result<Value>

Create one or more expectations from raw JSON values.

This is the lower-level counterpart to upsert for expectation shapes that the typed Expectation model does not (yet) cover — notably the httpLlmResponse action and conversation scenario fields produced by the crate::llm builders, and the Velocity/JSON-RPC expectations produced by the crate::mcp builder.

The expectations value should be a JSON object (single expectation) or a JSON array of expectation objects. Returns the raw JSON the server echoes back (or the submitted value if the server returns an empty body).

pub fn openapi( &self, expectation: &OpenApiExpectation, ) -> Result<Vec<Expectation>>

Register expectations from an OpenAPI/Swagger specification.

Sends a PUT /mockserver/openapi with the given OpenApiExpectation. MockServer parses the spec and creates request matchers and example responses for the selected operations (or every operation when none are specified). Returns the created expectations as echoed by the server.

Example

use mockserver_client::{ClientBuilder, OpenApiExpectation};

let client = ClientBuilder::new("localhost", 1080).build().unwrap();
client.openapi(
    &OpenApiExpectation::new("https://example.com/petstore.yaml")
        .operation("listPets", "200"),
).unwrap();

pub fn when(&self, request: HttpRequest) -> ForwardChainExpectation<'_>

Begin building an expectation with the fluent when(...).respond(...) API.

Example

use mockserver_client::{ClientBuilder, HttpRequest, HttpResponse};

let client = ClientBuilder::new("localhost", 1080).build().unwrap();
client.when(HttpRequest::new().method("GET").path("/foo"))
    .respond(HttpResponse::new().status_code(200).body("bar"))
    .unwrap();

pub fn verify( &self, request: HttpRequest, times: VerificationTimes, ) -> Result<()>

Verify that a request was received the specified number of times.

Returns Ok(()) if verification passes, or Err(Error::VerificationFailure) with the server’s failure message.

pub fn verify_request_and_response( &self, request: HttpRequest, response: HttpResponse, times: VerificationTimes, ) -> Result<()>

Verify that a request/response pair was received the specified number of times.

Both the request matcher and the response matcher must match for a recorded exchange to count. The response matcher uses the same HttpResponse type as expectations — the server matches against the recorded response’s status code, headers, and body.

pub fn verify_response( &self, response: HttpResponse, times: VerificationTimes, ) -> Result<()>

Verify that a response (regardless of request) was returned the specified number of times.

The httpRequest field is omitted from the JSON so the server matches any request.

pub fn verify_zero_interactions(&self) -> Result<()>

Verify that no requests at all were received by the server.

Thin wrapper over verify: matches any request (an empty matcher) with exactly(0) times. Returns Ok(()) if the server received no requests, or Err(Error::VerificationFailure) otherwise.

pub fn verify_raw(&self, verification: &Verification) -> Result<()>

Send a fully constructed Verification to the server.

This is the most flexible form — callers can set every field, including maximum_number_of_request_to_return_in_verification_failure.

pub fn verify_sequence(&self, requests: Vec<HttpRequest>) -> Result<()>

Verify that requests were received in the given order.

pub fn verify_sequence_with_responses( &self, requests: Vec<HttpRequest>, responses: Vec<HttpResponse>, ) -> Result<()>

Verify that request/response pairs were received in the given order.

responses is index-aligned with requests — each entry constrains the response that must have been returned for the corresponding request.

pub fn verify_sequence_raw( &self, verification: &VerificationSequence, ) -> Result<()>

Send a fully constructed VerificationSequence to the server.

pub fn clear( &self, request: Option<&HttpRequest>, clear_type: Option<ClearType>, ) -> Result<()>

Clear expectations and/or logs matching the given request.

If request is None, clears everything of the specified type.

pub fn clear_by_id( &self, expectation_id: impl Into<String>, clear_type: Option<ClearType>, ) -> Result<()>

Clear expectations by expectation ID.

pub fn reset(&self) -> Result<()>

Reset all expectations and recorded requests.

pub fn retrieve_recorded_requests( &self, request: Option<&HttpRequest>, ) -> Result<Vec<HttpRequest>>

Retrieve recorded requests matching the optional filter.

pub fn retrieve_active_expectations( &self, request: Option<&HttpRequest>, ) -> Result<Vec<Expectation>>

Retrieve active expectations matching the optional filter.

pub fn retrieve_recorded_expectations( &self, request: Option<&HttpRequest>, ) -> Result<Vec<Expectation>>

Retrieve recorded expectations matching the optional filter.

pub fn retrieve_expectations_as_code( &self, format: RetrieveFormat, request: Option<&HttpRequest>, ) -> Result<String>

Retrieve the active expectations as MockServer SDK setup code (the builder code that recreates the expectations) in the requested language.

format must be one of the code-generation variants of RetrieveFormat (e.g. RetrieveFormat::Java, RetrieveFormat::Rust). The generated code is returned as a string.

pub fn retrieve_recorded_expectations_as_code( &self, format: RetrieveFormat, request: Option<&HttpRequest>, ) -> Result<String>

Retrieve the recorded (proxied) request/response pairs as MockServer SDK setup code in the requested language.

format must be one of the code-generation variants of RetrieveFormat. The generated code is returned as a string.

pub fn retrieve_log_messages( &self, request: Option<&HttpRequest>, ) -> Result<Vec<String>>

Retrieve log messages matching the optional filter.

pub fn retrieve_request_responses( &self, request: Option<&HttpRequest>, ) -> Result<Vec<Value>>

Retrieve recorded request/response pairs.

pub fn status(&self) -> Result<Ports>

Query the server’s listening ports.

pub fn bind(&self, ports: &[u16]) -> Result<Ports>

Bind additional listening ports.

pub fn has_started(&self, attempts: u32, timeout_ms: u64) -> bool

Check if the MockServer has started (polls with retries).

pub fn add_breakpoint( &self, matcher: HttpRequest, phases: &[&str], request_handler: Option<BreakpointRequestHandler>, response_handler: Option<BreakpointResponseHandler>, stream_frame_handler: Option<BreakpointStreamFrameHandler>, ) -> Result<String>

Register a breakpoint matcher with the given phases and handlers. Returns the server-assigned breakpoint id.

pub fn add_request_breakpoint( &self, matcher: HttpRequest, handler: BreakpointRequestHandler, ) -> Result<String>

Convenience: register a REQUEST-only breakpoint.

pub fn add_request_response_breakpoint( &self, matcher: HttpRequest, request_handler: BreakpointRequestHandler, response_handler: BreakpointResponseHandler, ) -> Result<String>

Convenience: register a REQUEST + RESPONSE breakpoint.

pub fn add_stream_breakpoint( &self, matcher: HttpRequest, phases: &[&str], handler: BreakpointStreamFrameHandler, ) -> Result<String>

Convenience: register a streaming-phase breakpoint.

pub fn list_breakpoint_matchers(&self) -> Result<BreakpointMatcherList>

List all registered breakpoint matchers.

pub fn remove_breakpoint_matcher(&self, id: impl Into<String>) -> Result<()>

Remove a breakpoint matcher by id.

pub fn clear_breakpoint_matchers(&self) -> Result<()>

Remove all registered breakpoint matchers.

pub fn close_breakpoint_websocket(&self)

Close the breakpoint callback WebSocket connection.

pub fn mock_with_callback<F>( &self, matcher: HttpRequest, handler: F, ) -> Result<Vec<Expectation>>

where F: Fn(HttpRequest) -> HttpResponse + Send + 'static,

Register an expectation whose response is produced by a Rust closure invoked over the callback WebSocket (an httpResponseObjectCallback).

When a request matches matcher, MockServer pushes it to this client over the shared callback WebSocket; handler receives the HttpRequest and returns the HttpResponse to send back. The closure runs on the client’s background WebSocket-read thread, so it must be Send + 'static.

The callback WebSocket is shared with breakpoints — only one socket is opened per client. There is a single object-response handler per client; calling this again replaces it. Narrow which requests reach the closure with the matcher.

Example

use mockserver_client::{ClientBuilder, HttpRequest, HttpResponse};

let client = ClientBuilder::new("localhost", 1080).build().unwrap();
client.mock_with_callback(
    HttpRequest::new().method("GET").path("/echo"),
    |req| {
        HttpResponse::new()
            .status_code(200)
            .body(format!("you asked for {}", req.path.unwrap_or_default()))
    },
).unwrap();

pub fn upload_grpc_descriptor(&self, descriptor: &[u8]) -> Result<()>

Upload a compiled protobuf descriptor set so gRPC requests can be matched.

descriptor must be the raw bytes of a FileDescriptorSet (e.g. the output of protoc --descriptor_set_out=... --include_imports). The bytes are sent verbatim as application/octet-stream — they are not base64-encoded. Sends a PUT /mockserver/grpc/descriptors; the server responds 201 Created on success.

Example

use mockserver_client::ClientBuilder;

let client = ClientBuilder::new("localhost", 1080).build().unwrap();
let descriptor_set: Vec<u8> = std::fs::read("greeter.desc").unwrap();
client.upload_grpc_descriptor(&descriptor_set).unwrap();

pub fn retrieve_grpc_services(&self) -> Result<Vec<GrpcService>>

Retrieve the gRPC services registered from uploaded descriptor sets.

Sends a PUT /mockserver/grpc/services and returns the parsed list of GrpcServices, each with its GrpcMethods.

pub fn clear_grpc_descriptors(&self) -> Result<()>

Clear all uploaded gRPC descriptor sets and registered services.

Sends a PUT /mockserver/grpc/clear; the server responds 200 OK.

pub fn scenario(&self, name: &str) -> Scenario<'_>

Obtain a handle for inspecting and driving a named scenario state-machine.

The returned Scenario borrows the client and issues control-plane requests against /mockserver/scenario/{name}.

Example

use mockserver_client::ClientBuilder;

let client = ClientBuilder::new("localhost", 1080).build().unwrap();
client.scenario("Deploy").set("Deploying").unwrap();
client.scenario("Deploy").set_timed("Deploying", 5000, "Deployed").unwrap();
client.scenario("Deploy").trigger("Failed").unwrap();
let state = client.scenario("Deploy").state().unwrap();
assert_eq!(state, "Failed");

pub fn scenarios(&self) -> Result<Vec<ScenarioState>>

List every known scenario and its current state.

Sends a GET /mockserver/scenario and returns the parsed list of ScenarioStates.

pub fn load_scenario(&self, scenario: &LoadScenario) -> Result<Value>

Register (load) a load scenario in the registry without running it.

Sends a PUT /mockserver/loadScenario with the given LoadScenario. The scenario’s name is the unique registry key used later by start_load_scenarios / stop_load_scenarios and the per-scenario fetch/delete endpoints.

Registering is always allowed — even when load generation is disabled on the server — so this does not surface Error::FeatureDisabled. Returns the raw JSON the server echoes ({"name":..,"state":"LOADED"}).

pub fn load_scenarios(&self) -> Result<Value>

List every registered load scenario.

Sends a GET /mockserver/loadScenario and returns the raw JSON ({"scenarios":[{"name":..,"state":..,"definition":..,"status":..?}]}).

pub fn get_load_scenario(&self, name: impl AsRef<str>) -> Result<Value>

Fetch a single registered load scenario by name.

Sends a GET /mockserver/loadScenario/{name}. Returns Error::NotFound when no scenario with that name is registered.

pub fn delete_load_scenario(&self, name: impl AsRef<str>) -> Result<Value>

Remove a single registered load scenario by name.

Sends a DELETE /mockserver/loadScenario/{name}. Returns Error::NotFound when no scenario with that name is registered.

pub fn clear_load_scenarios(&self) -> Result<Value>

Clear all registered load scenarios.

Sends a DELETE /mockserver/loadScenario. Idempotent.

pub fn start_load_scenarios<S: AsRef<str>>(&self, names: &[S]) -> Result<Value>

Start one or more registered load scenarios by name.

Sends a PUT /mockserver/loadScenario/start with {"names":[...]}. Requires load generation to be enabled on the server — returns Error::FeatureDisabled on 403 (loadGenerationEnabled=false) — and Error::NotFound when a name is not registered. Honours each scenario’s startDelayMillis. Returns the raw JSON ({"started":[{"name":..,"state":..}],"status":..}).

pub fn stop_load_scenarios<S: AsRef<str>>(&self, names: &[S]) -> Result<Value>

Stop running load scenarios.

Sends a PUT /mockserver/loadScenario/stop. When names is non-empty the body is {"names":[...]}; when it is empty (or &[]) the body is empty, which the server treats as “stop all”. Returns the raw JSON ({"stopped":[..],"status":..}).

pub fn run_load_scenario(&self, scenario: &LoadScenario) -> Result<Value>

Convenience: register scenario then immediately start it by name.

Equivalent to load_scenario followed by start_load_scenarios with the scenario’s own name. Returns the JSON from the start call. Surfaces Error::FeatureDisabled from start when load generation is disabled.

pub fn get_load_scenario_report( &self, name: impl AsRef<str>, format: Option<&str>, ) -> Result<String>

Fetch the end-of-run summary report for a load scenario run.

Sends a GET /mockserver/loadScenario/{name}/report. When format is Some("junit") a ?format=junit query is appended and the server returns a JUnit-XML <testsuite> document; omit format (None) for the JSON report. The raw response body is returned as a string so either form (JSON or XML) passes through verbatim. Returns Error::NotFound when the scenario never ran.

pub fn generate_load_scenario_from_openapi<T: Serialize + ?Sized>( &self, body: &T, ) -> Result<Value>

Generate (and register) an editable load scenario from an OpenAPI spec.

Sends a PUT /mockserver/loadScenario/generateFromOpenAPI. The body carries the generated scenario name, the specUrlOrPayload, and an optional target and profile. Like load_scenario this only registers (LOADED) the scenario — it generates no traffic and is allowed even when load generation is disabled. Returns the raw JSON ({"status":"loaded","name":..,"state":..,"scenario":..}).

pub fn generate_load_scenario_from_recording<T: Serialize + ?Sized>( &self, body: &T, ) -> Result<Value>

Generate (and register) an editable load scenario from recorded proxy traffic.

Sends a PUT /mockserver/loadScenario/generateFromRecording. The body carries the generated scenario name and the recording selection/options. Like load_scenario this only registers (LOADED) the scenario — it generates no traffic. Returns the raw JSON ({"status":"loaded","name":..,"state":..,"scenario":..}).

pub fn set_service_chaos( &self, host: impl Into<String>, profile: &HttpChaosProfile, ttl_millis: Option<u64>, ) -> Result<Value>

Register a service-scoped HTTP chaos profile for a downstream host.

Sends a PUT /mockserver/serviceChaos. ttl_millis, when supplied, sets an optional time-to-live after which the registration auto-reverts. Returns the raw JSON the server echoes.

pub fn remove_service_chaos(&self, host: impl Into<String>) -> Result<Value>

Remove a single host’s service-scoped chaos profile.

Sends a PUT /mockserver/serviceChaos with {"host":..,"remove":true}.

pub fn clear_service_chaos(&self) -> Result<Value>

Clear all service-scoped chaos.

Sends a PUT /mockserver/serviceChaos with {"clear":true}.

pub fn verify_slo(&self, criteria: &SloCriteria) -> Result<SloVerdict>

Verify a set of service-level objectives over a window.

Sends a PUT /mockserver/verifySLO. The HTTP status encodes the verdict: 200 for PASS or INCONCLUSIVE, 406 for FAIL — both deserialize into a SloVerdict (inspect SloVerdict::result). A 400 (malformed criteria, or SLO tracking disabled) surfaces as Error::FeatureDisabled.

Returns Ok(SloVerdict) for both PASS/INCONCLUSIVE (200) and FAIL (406) so callers can branch on the verdict; transport/parse failures and 400 are returned as Err.

pub fn set_preemption( &self, request: &PreemptionRequest, ) -> Result<PreemptionStatus>

Cordon and drain the server (preemption simulation).

Sends a PUT /mockserver/preemption with the given PreemptionRequest and returns the resulting PreemptionStatus.

pub fn preemption_status(&self) -> Result<PreemptionStatus>

Retrieve the current preemption status.

Sends a GET /mockserver/preemption and returns the PreemptionStatus.

pub fn clear_preemption(&self) -> Result<Value>

Uncordon the server (clear any active preemption simulation).

Sends a DELETE /mockserver/preemption. Idempotent — succeeds whether or not a simulation was active. Returns the raw JSON status.

pub fn start_chaos_experiment( &self, experiment: &ChaosExperiment, ) -> Result<Value>

Start a scheduled multi-stage chaos experiment.

Sends a PUT /mockserver/chaosExperiment with the given ChaosExperiment. Only one experiment may be active at a time; starting a new one stops the previous one. Returns the raw JSON status ({"status":"started","name":..}).

pub fn freeze_clock(&self, instant: Option<&str>) -> Result<String>

Freeze the simulated clock (PUT /mockserver/clock, action=freeze).

Pass Some(instant) — an ISO-8601 instant string such as "2024-01-01T00:00:00Z" — to freeze at a specific time, or None to freeze at the current time. Returns the clock-status JSON the server echoes back.

pub fn advance_clock(&self, duration_millis: i64) -> Result<String>

Advance the simulated clock by duration_millis (PUT /mockserver/clock, action=advance). The value must be positive — the server returns 400 for <= 0. Returns the clock-status JSON the server echoes back.

pub fn reset_clock(&self) -> Result<String>

Reset the simulated clock back to the real system clock (PUT /mockserver/clock, action=reset). Returns the clock-status JSON.

pub fn clock_status(&self) -> Result<String>

Read the current clock status (GET /mockserver/clock). Returns the JSON body verbatim, e.g. {"currentInstant":"...","currentEpochMillis":...,"frozen":true}.

pub fn retrieve_metrics(&self) -> Result<String>

Retrieve the JSON metrics counter snapshot (PUT /mockserver/retrieve?type=METRICS). Returns a flat JSON object mapping each metric name to its long value ({} when metrics are disabled).

pub fn scrape_metrics(&self) -> Result<String>

Scrape the Prometheus exposition metrics (GET /mockserver/metrics). Returns the exposition text. When metrics are disabled the server replies 404, surfaced as Error::NotFound.

pub fn retrieve_configuration(&self) -> Result<String>

Read the effective live configuration (GET /mockserver/configuration). Returns the serialized Configuration JSON.

pub fn update_configuration(&self, config_json: &str) -> Result<String>

Update the live configuration (PUT /mockserver/configuration).

config_json is a ConfigurationDTO JSON document — only the fields present are applied (partial update). Returns the serialized updated configuration JSON.

pub fn retrieve_drift(&self) -> Result<String>

Retrieve the recorded mock drift report (GET /mockserver/drift).

Returns the serialized report JSON, of the form {"count": <n>, "drifts": [ ... ]}, where each entry describes a difference detected between a mock’s configured response and the live upstream response for the same request.

pub fn clear_drift(&self) -> Result<()>

Clear all recorded mock drift (PUT /mockserver/drift/clear).

pub fn pact_import(&self, json: &str) -> Result<Vec<Expectation>>

Import a Pact v3 contract (PUT /mockserver/pact/import).

Returns the JSON array of upserted expectations the server creates.

pub fn pact_export(&self, consumer: &str, provider: &str) -> Result<String>

Export the active expectations as a Pact v3 contract (PUT /mockserver/pact?consumer=&provider=).

A query parameter is only added when the corresponding value is non-blank (matching the Java client); blank values fall back to the server defaults. Returns the generated Pact JSON.

pub fn pact_verify(&self, json: &str) -> Result<PactVerification>

Verify a Pact v3 contract against the active expectations (PUT /mockserver/pact/verify).

The verification outcome is returned in the Ok value rather than as an error: 202 ACCEPTED maps to PactVerification with passed = true and 406 NOT_ACCEPTABLE to passed = false. Both carry the server’s verification report. A 400 (bad input) is surfaced as Error::InvalidRequest.

pub fn store_file(&self, name: &str, content: &[u8]) -> Result<String>

Store a file in the in-memory file store (PUT /mockserver/files/store).

content is sent base64-encoded (with "base64": true) so arbitrary binary data round-trips intact. Returns the {"name":..,"size":..} JSON.

pub fn retrieve_file(&self, name: &str) -> Result<Vec<u8>>

Retrieve a file’s raw bytes (PUT /mockserver/files/retrieve).

Returns the raw 200 body bytes. An unknown file (404) is surfaced as Error::NotFound (mirroring the crate’s status-to-error mapping).

pub fn list_files(&self) -> Result<Vec<String>>

List the names of all stored files (PUT /mockserver/files/list).

pub fn delete_file(&self, name: &str) -> Result<()>

Delete a stored file (PUT /mockserver/files/delete). An unknown file (404) is surfaced as Error::NotFound.

pub fn import_har(&self, har_json: &str) -> Result<Vec<Expectation>>

Import a HAR document (PUT /mockserver/import?format=har). Returns the upserted expectations.

pub fn import_postman_collection( &self, collection_json: &str, ) -> Result<Vec<Expectation>>

Import a Postman collection (PUT /mockserver/import?format=postman). Returns the upserted expectations.

pub fn set_mode(&self, mode: MockMode) -> Result<String>

Set the high-level operating mode (PUT /mockserver/mode?mode=<MODE>). Returns the {"mode":..,"proxyUnmatchedRequests":..} JSON.

pub fn retrieve_mode(&self) -> Result<String>

Read the current operating mode (GET /mockserver/mode). Returns the {"mode":..,"proxyUnmatchedRequests":..} JSON.

pub fn wsdl_expectation(&self, wsdl: &str) -> Result<Vec<Expectation>>

Generate expectations from a WSDL document (PUT /mockserver/wsdl).

The raw WSDL XML is sent as the request body (Content-Type text/xml). Returns the generated (upserted) expectations.