v6.1.0

Security

• SSRF protection for forward and forward-template actions: new mockserver.forwardProxyBlockPrivateNetworks property (default false for backwards compatibility) rejects forward targets that resolve to loopback, link-local, RFC 1918 private, or cloud metadata addresses (e.g. 169.254.169.254). Enable in hardened or multi-tenant deployments where untrusted callers can register expectations. A future major release is expected to flip the default to true.
• ReDoS protection in regex matchers: regex evaluation now runs on a shared cached daemon-thread pool with a configurable timeout mockserver.regexMatchingTimeoutMillis (default 5000ms). Patterns that exceed the budget are treated as non-matches and a WARN log entry is written, so a pathological pattern cannot wedge a Netty worker.
• XPath DoS protection: XPath evaluation in body matching now uses the same shared timeout executor with mockserver.xpathMatchingTimeoutMillis (default 5000ms).
• Cryptographically secure randomness: UUIDService and TemplateFunctions now use SecureRandom instead of java.util.Random for UUID generation, rand_int/rand_int_10/rand_int_100, and rand_bytes template helpers.
• Loud insecure-mode warning logs at startup / SSL-context init: a WARN is emitted when (a) the forward proxy trusts all TLS certificates (forwardProxyTLSX509CertificatesTrustManagerType=ANY), (b) Velocity class loading is enabled (velocityDisallowClassLoading=false), (c) JavaScript templates have no class restrictions (javascriptDisallowedClasses empty), or (d) tlsProtocols includes the deprecated TLSv1 / TLSv1.1.
• mockserver.tlsAllowInsecureProtocols configuration property (default true for backwards compatibility): when set to false, any TLSv1 or TLSv1.1 entries in mockserver.tlsProtocols are filtered out before the SSL context is built, giving users an opt-in hardened TLS profile without having to rewrite their existing tlsProtocols value. A future major release is expected to flip this default to false.

Added

• First-class LLM and agent mocking: new httpLlmResponse action type lets you mock LLM provider APIs at the semantic level — describe the model's reply (text, tool calls, stop reason, usage) and MockServer produces the byte-correct provider wire format. Supports all 7 major providers: Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, Google Gemini, AWS Bedrock, Azure OpenAI, and Ollama. Non-streaming responses return provider-correct JSON; streaming responses generate the full SSE event sequence (e.g. message_start through message_stop for Anthropic, chat.completion.chunk with finish_reason for OpenAI) with configurable timing physics (timeToFirstToken, tokensPerSecond, jitter). OpenAI embeddings are also supported with deterministic vector generation via deterministicFromInput().
• Conversation-aware matchers for multi-turn agent testing: whenTurnIndex(n), whenLatestMessageContains(text), whenLatestMessageRole(role), and whenContainsToolResultFor(toolName) predicates match against the parsed messages array in the inbound request body, enabling scripted multi-turn conversations where turn 1 returns a tool_use and turn 2 (after the agent sends a tool_result) returns the final answer. All predicates compose with AND semantics and integrate with the scenario state machine for automatic turn advancement.
• Per-session conversation isolation via isolateBy(header("x-session-id")), isolateBy(queryParameter("agent")), or isolateBy(cookie("sid")): each unique value of the configured attribute gets independent scenario state, so concurrent agents sharing the same mocked endpoint do not interfere. Missing attributes fall back to shared state gracefully.
• mock_llm_completion MCP tool: set up a single-turn LLM expectation from the MCP control plane, specifying provider, path, model, text, tool calls, and streaming mode
• create_llm_conversation MCP tool: build a multi-turn scenario-chained LLM conversation with optional per-session isolation from the MCP control plane; returns the generated scenario name and per-turn state values
• LLM Response badge in the dashboard expectation row showing provider, model, and text preview; Conversation view extended with a scripted-turns panel
• mockserver.maxLlmConversationBodySize configuration property (default 1 MiB; clamped to 16 KiB - 64 MiB; env var MOCKSERVER_MAX_LLM_CONVERSATION_BODY_SIZE): request bodies larger than this limit skip conversation-aware parsing and are treated as no-match, preventing DoS via oversized JSON payloads
• Custom json-unit matcher support for JSON body matching: implement org.mockserver.matchers.CustomJsonUnitMatcherProvider and point mockserver.customJsonUnitMatchersClass at it to register named Hamcrest matchers that JSON body expectations can reference via the ${json-unit.matches:name} placeholder (e.g. { "price": "${json-unit.matches:largerThan}" }); misconfigured providers are logged at WARN and ignored, so matching never fails because of an unloadable extension (fixes #​2279)
• http2Enabled configuration property to disable HTTP/2: when set to false ALPN no longer advertises h2 (and h2c is not detected) so HTTP/2 capable clients fall back to HTTP/1.1
• Agent-friendly mismatch diagnostics: explain_unmatched_requests MCP tool and PUT /mockserver/explainUnmatched REST endpoint return recent requests that matched no expectation, each with ranked closest-expectation diffs and actionable remediation hints (e.g., "use method POST not GET", "add missing header Authorization"); debug_request_mismatch results are now ranked by closeness and include remediation hints; new mockserver://unmatched MCP resource
• create_expectations_from_recorded_traffic MCP tool: converts traffic recorded by MockServer's forwarding/proxy mode into active mock expectations in one call, enabling an "observe then mock" workflow; supports method/path filtering and preview mode to inspect expectations before activating them
• OpenAPI contract verification MCP tools: verify_traffic_against_openapi validates recorded request-response pairs against an OpenAPI spec (passive conformance checking); run_contract_test sends example requests derived from an OpenAPI spec to a running service and validates the responses (active contract testing); both return structured per-operation pass/fail results with validation errors
• OpenAPI resiliency testing MCP tool: run_resiliency_test sends deliberately malformed and boundary-case requests derived from an OpenAPI spec to a running service (omitting required fields, type violations, numeric/string boundary violations, oversized strings, malformed JSON) and classifies each outcome as HANDLED (4xx) or UNEXPECTED (5xx/2xx/error); returns per-mutation results with operation summaries
• Deterministic LLM record/replay: record_llm_fixtures MCP tool snapshots LLM/MCP traffic recorded through MockServer's forwarding proxy into a committable JSON fixture file with secrets automatically redacted (Authorization, api-key, Cookie, etc.); SSE streaming responses (Anthropic, OpenAI, etc.) are converted to HttpSseResponse actions for faithful event-by-event replay; load_expectations_from_file MCP tool loads fixture files as active expectations for offline, deterministic, zero-cost test replay

Changed

• BREAKING Inbound HTTP/1.1 and HTTP/2 request bodies are now capped at 10 MiB by default (mockserver.maxRequestBodySize). Previously unbounded. Requests larger than the limit are rejected with 413 Payload Too Large. Raise the limit (e.g. -Dmockserver.maxRequestBodySize=52428800) if you intentionally mock large uploads.
• BREAKING Upstream response bodies received when MockServer is acting as a proxy or forwarder are now capped at 50 MiB by default (mockserver.maxResponseBodySize). Previously unbounded. Raise if you forward to services that legitimately return larger payloads.
• Each published JAR (including the -no-dependencies shaded artifacts) now declares a stable Automatic-Module-Name in its MANIFEST.MF, so downstream JPMS consumers can requires MockServer modules with names that no longer change with each version: org.mockserver.core (mockserver-core), org.mockserver.client (mockserver-client-java), org.mockserver.netty (mockserver-netty), org.mockserver.test (mockserver-testing), org.mockserver.testing (mockserver-integration-testing), org.mockserver.junit.rule (mockserver-junit-rule), org.mockserver.junit.jupiter (mockserver-junit-jupiter), org.mockserver.springtest (mockserver-spring-test-listener), org.mockserver.examples (mockserver-examples), org.mockserver.maven (mockserver-maven-plugin); each *-no-dependencies shaded variant shares its unshaded counterpart's module name and is an alternative packaging (place only one on the JPMS module path)

Fixed

• Dynamic CA / SSL certificate generation no longer fails when dynamicallyCreateCertificateAuthorityCertificate=true (or any auto-generated server certificate path) is used: the four Configuration fluent setters for certificateAuthorityCertificate, certificateAuthorityPrivateKey, privateKeyPath, and x509CertificatePath no longer file-existence-check at set-time, because the internal generator sets these to the destination path before the file is written. User-supplied path typos are still surfaced by CertificateConfigurationValidator at TLS-init time.
• HTTP/2 requests through the HTTPS CONNECT forward proxy no longer hang and emit a GOAWAY after ~30s; the internal relay now negotiates HTTP/1.1 or HTTP/2 per connection via ALPN instead of mismatching its TLS layer and codec (fixes #​2260)
• Docker image and standalone executable JAR produced no log output because the shaded server JAR did not include an SLF4J logging provider (fixes #​2097)
• *-no-dependencies shaded artifacts leaked their un-shaded source module (and its transitive dependencies) onto consumers' classpaths; these artifacts are now truly dependency-free

v6.0.0

Added

Protocol & transport

• gRPC protocol mocking without a grpc-java dependency: upload a Protobuf descriptor and mock unary, client-streaming, server-streaming, and bidirectional-streaming RPCs; GrpcStreamResponse supports multi-frame streaming responses
• GraphQL body matching: whitespace-normalised query comparison, operationName matching, and variablesSchema JSON Schema validation for variables
• binary request/response mocking via BinaryRequestDefinition and BinaryResponse for non-HTTP protocols
• DNS mocking with dnsEnabled/dnsPort configuration and support for A, AAAA, CNAME, MX, SRV, TXT, and PTR record types
• IPv6 CONNECT proxy support including correctly bracketed IPv6 address handling in the CONNECT tunnel

Request matching

• probabilistic expectation matching: set a percentage field (0–100) on an expectation so only a fraction of matching requests are served by it, enabling fault-injection scenarios (fixes #​2122)
• HTTP method factory methods on HttpRequest: HttpRequest.get(path), .post(path), .put(path), .delete(path), .patch(path), .head(path), .options(path) for more concise expectation definitions (fixes #​1509)

Responses & actions

• multi-response expectations: define an httpResponses list with a responseMode of SEQUENTIAL (cycle repeatedly through the list in order) or RANDOM (pick at random) to serve different responses on successive matched requests
• multi-action expectations: compose response, forward, and callback actions in a single expectation with a primary action and post-action callbacks
• stateful scenarios with atomic state transitions: gate expectations behind named states and advance through them by setting newScenarioState on the expectation, making it straightforward to model multi-step protocols
• CRUD simulation via PUT /mockserver/crud: supply a data model and MockServer auto-generates a fully stateful REST API (list, create, read, update, delete) backed by an in-memory store
• FileBody response body type that loads content from a file path at response time, useful for large or binary payloads (fixes #​2163)
• in-memory file store: upload files via PUT /mockserver/files/store, retrieve via PUT /mockserver/files/retrieve, list via PUT /mockserver/files/list, and delete via PUT /mockserver/files/delete; stored files can be referenced by FileBody (fixes #​1652)
• respondBeforeBody flag on the request matcher to dispatch the configured response (and optionally close the connection) before MockServer reads the request body, useful for reproducing client behaviour when a server responds and closes mid-upload (fixes #​1831)

Delays & timing

• response delays with statistical distributions (uniform, Gaussian, log-normal) for realistic latency simulation (fixes #​1688)
• global response delay via mockserver.globalResponseDelayMillis configuration property to add a baseline delay to every response
• connection timeout emulation via mockserver.connectionDelayMillis configuration property: a configurable delay before protocol detection fires, so slow-connect scenarios can be tested without a real network (fixes #​1604)
• chunked dribble delay via ConnectionOptions.withChunkSize() / withChunkDelay() to drip-feed any response body in configurable-size chunks at a configurable rate

Response templates

• template helper functions: JWT generation, string manipulation, JSON path extraction, date arithmetic, and math operations available inside JavaScript, Velocity, and Mustache templates

Record & replay

• HAR 1.2 export: pass format=HAR to the retrieve API to get a standard HAR file of all recorded requests and responses (fixes #​2175)
• automatic persistence of recorded expectations: persistRecordedExpectations and persistedRecordedExpectationsPath configuration properties save recorded traffic to disk so it survives restarts (fixes #​2175)

Debugging & diagnostics

• per-expectation match count tracking: each expectation now exposes an invocation counter so tests can assert exactly how many times an endpoint was hit
• closest-match tracking: when a request does not match any expectation, MockServer identifies the expectation with the most fields satisfied and surfaces it via the API and dashboard
• debugMismatch() client method and PUT /mockserver/debugMismatch endpoint to programmatically retrieve the closest-match analysis for the last unmatched request
• match failure hints: actionable suggestions attached to EXPECTATION_NOT_MATCHED log events to guide correction of common mistakes
• "Why didn't this match?" debug dialog in the dashboard: click any unmatched request to see a field-by-field comparison against the closest expectation with per-field pass/fail indicators
• expectation ID included in EXPECTATION_NOT_MATCHED log messages to make it easier to correlate log output with the intended expectation (fixes #​1937)

Logging

• compact log format: set mockserver.compactLogFormat=true to emit single-line JSON log entries instead of multi-line formatted output (fixes #​1510)
• per-category log level overrides via mockserver.logLevelOverrides so individual event types can have different log levels (fixes #​1694)
• correlation ID retrieval: retrieveLogsByCorrelationId() client method and a correlationId chip in the dashboard for tracing a single request across all related log events
• retrieveLogEntries() client method returning typed LogEntry objects with optional time-range filtering; pass LOG_ENTRIES as the format to the retrieve API for programmatic access
• custom log event listener via a Consumer<LogEntry> callback registered with the Configuration object, enabling integration with external observability tools (fixes #​1960)

Proxy & forwarding configuration

• mockserver.forwardDefaultHostHeader configuration property: set a specific Host header value to send on all forwarded requests, overriding the original client Host header (fixes #​1782)
• mockserver.proxyRemoteHost and mockserver.proxyRemotePort configuration properties to route all proxy traffic through an upstream proxy (fixes #​1753)
• request forwarding timings captured per forwarded request: both connect time and total round-trip time are available in the log and dashboard (fixes #​1574)

OpenAPI

• OpenAPI callback support: MockServer reads callbacks entries in an OpenAPI specification and automatically creates AfterAction webhook expectations (fixes #​1483)

TLS & security

• BouncyCastle FIPS provider support for environments that require FIPS 140-2 compliant cryptography (fixes #​1769)
• support for custom TLS protocols TLSv1.2 and TLSv1.3
• better error messages when MockServerClient fails due to TLS or networking errors

Client & test integration

• @MockServerTest now applies mockserver.* prefixed properties to the per-instance MockServer Configuration object, enabling declarative configuration of initializationClass, logLevel, maxExpectations, and other settings directly in the annotation (fixes #​1554)
• Jackson StreamReadConstraints maximum string length raised to 100 MB to handle large JSON bodies without StreamConstraintsException (fixes #​1754)

Build & deployment

• Maven plugin initializationJson now accepts glob patterns to load multiple expectation files from a directory (fixes #​2231)
• mockserver/mockserver:graaljs Docker image tag that bundles the GraalJS engine JARs, enabling native ECMAScript 2022 support in response templates without Nashorn
• Docker HEALTHCHECK instruction added to all official images so container orchestrators can determine readiness without an external probe
• Helm chart podLabels value to attach arbitrary labels to MockServer pods, useful for service-mesh injection and internal routing rules (fixes #​1884)

Changed

• BREAKING: removed implicit reliance on internal java-certificate-classes (thanks to @​Arkinator)
• BREAKING: the classifier=shaded form of mockserver-client-java, mockserver-netty, mockserver-junit-jupiter, mockserver-junit-rule, and mockserver-spring-test-listener is no longer published. Use the corresponding *-no-dependencies artifactId instead (e.g. depend on mockserver-netty-no-dependencies rather than mockserver-netty with <classifier>shaded</classifier>). The *-no-dependencies variants are now proper Maven modules and are the supported way to consume a shaded MockServer jar.

Fixed

Proxy & forwarding

• proxy forwarding failures now return 502 Bad Gateway instead of 404 Not Found, making it clearer to clients that the upstream could not be reached (fixes #​1519)
• Host header updated to match the forwarding target to prevent 421 Misdirected Request errors from strict servers (fixes #​1897)
• request/response bodies with Content-Encoding are now re-compressed correctly when forwarding, preventing garbled bodies on the upstream (fixes #​1668)
• Transfer-Encoding header preserved on forwarded responses; spurious Content-Length header no longer added when Transfer-Encoding is present (fixes #​1733)

Request & response handling

• cookie values starting with ! were corrupted in forwarded responses (fixes #​1875)
• duplicate query parameter values are now preserved instead of being deduplicated (fixes #​1866)
• binary response bodies (e.g. application/octet-stream; charset=utf-8) were corrupted because a charset parameter in Content-Type caused the body to be treated as a string; now correctly treated as binary (fixes #​1910)
• JSON body serialization preserved numeric precision — 0.00 was incorrectly serialized as 0.0 (fixes #​1740)

OpenAPI

• ByteArraySchema (string format byte) properties were omitted from generated OpenAPI examples (fixes #​1788)
• $ref inside OpenAPI example values was not resolved, leading to raw $ref strings in generated responses (fixes #​1474)
• allOf/anyOf/oneOf composed schemas now generate merged example responses (fixes #​1852)
• OAS 3.0 boolean exclusiveMinimum/exclusiveMaximum now correctly translated to JSON Schema Draft-07 numeric format (fixes #​1896)
• OpenAPI 3.1 types array field now correctly preserved during schema serialization (fixes #​1940)

XML

• XSD schemas with xs:include or xs:import using relative paths now resolve correctly (fixes #​2118)

JUnit & Spring integration

• @MockServerTest field injection now works in @Nested JUnit 5 test classes (fixes #​1979)
• double server start when @MockServerSettings (carrying @ExtendWith) is combined with explicit MockServerExtension registration is now prevented (fixes #​1977)
• clientCertificateChain, localAddress, and remoteAddress fields on HttpRequest were serialized but not deserialized — both directions now work (fixes #​1973)
• MockServerClient parameter injection now works with @TestInstance(PER_CLASS) where the test instance is created before @BeforeAll (fixes #​1621)
• ClassNotFoundException for callback classes when running in a Spring Boot uber JAR (fixes #​1571)

Dashboard & WebSocket

• dashboard WebSocket returned 404 when MockServer was running behind a reverse proxy with a path prefix (fixes #​1693)
• HTTP/2 CONNECT proxy no longer hangs when the client advertises h2 via ALPN (fixes #​1933)
• WebSocket upgrade over HTTP/2 is now rejected cleanly instead of hanging the dashboard (fixes #​1803)

Concurrency & thread safety

• Times.remainingTimes() made thread-safe with AtomicInteger to prevent race conditions under concurrent load (fixes #​1834)
• XmlStringMatcher made thread-safe by creating a new DiffBuilder per match instead of sharing one (fixes #​1796)
• Disruptor ring buffer is drained before verify() to prevent false-positive or false-negative results under high throughput (fixes #​1757)
• expired TTL expectations are now filtered from the event bus and event bus subscribers are cleared after publish to prevent stale matches (fixes #​1847, #​1874)

TLS & mTLS

• mTLS (data-plane) enforcement moved from transport layer to application layer, fixing scenarios where client certificate validation was applied to non-mTLS connections (fixes #​1766)

Docker & deployment

• netty-tcnative native libraries no longer bundled in the shaded JAR, preventing native library conflicts (fixes #​1778)
• Helm chart sub-chart deployments generated conflicting Kubernetes resource names when chart name was omitted (fixes #​1752)

Glob & file initialization

• glob brace expansion in initializationJson path failed to find the starting directory in some environments (fixes #​1715)
• WebSocket channel leak when the CircularHashMap evicted the oldest callback client (fixes #​1543)
• verify failure message incorrectly said "was not found" even when matching requests existed; message now accurately describes the mismatch (fixes #​1789)