npm / mockttp
mockttp
What changed in mockttp 2 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-25.
61 breaking21 new APIs and options1 behavior and defaults1 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initmockttp 443 changes
Breaking changes 31
Removed from TLS events because its meaning was ambiguous; use event.destination or event.tlsMetadata.sniHostname depending on the use case.
Removed from TLS events because its meaning was ambiguous; use event.destination for the tunnel target.
Provides the servername specified in the TLS SNI extension as an alternative to the removed TLS event properties.
The passthrough rules forwarding option has moved into transformRequest URL rewriting options; simple cases can use replaceHost.
Subject-related options have moved into a separate subject options field.
Generated CA certificate key PEMs now use PKCS#8 format instead of PKCS#1.
A modern Mockttp client controlling an old Mockttp server may have issues; a v4 client controlling any previous Mockttp version is unsupported.
Manual rule definitions now use steps instead of a single handler field.
Removed from TLS, request, and websocket events; use event.url, event.destination, or the appropriate host header instead.
Removed type alias; use CertDataOptions instead.
Removed type alias; use CertPathOptions instead.
The minimum Node version is now 20; Node 18 may continue to work for now but may stop working unpredictably in a future release.
On Node 22.13 and later, proxied requests no longer automatically receive transfer-encoding and connection headers; invalid requests may need fixing or a beforeRequest callback.
Proxy-connection and proxy-authorization headers are now preprocessed and stripped before events, including for direct requests.
Proxy-connection and proxy-authorization headers are now preprocessed and stripped before events, including for direct requests.
Explicitly proxied destinations now take precedence over mismatching host or :authority header values, including in the url property.
Only real RegExp instances are treated as regular expressions; regex-compatible objects are no longer accepted.
Remote clients and browser usage now receive body content decoded on the server, removing the need for client-side decoding libraries; event delivery timing may differ.
Adds host rewriting to request transform options for HTTP requests and websockets.
Step definitions are exported as requestSteps; implementations are no longer exported and Handler names have been replaced with Step names.
Renamed to FixedResponseHandler.
Renamed to FlexiblePathMatcher.
Upstream ECONNRESET errors are simulated downstream only when this option is set.
The callback result field was removed; use statusCode instead.
Manual rule handlers are now steps and can be multiple; replace handler: X with steps: [X] in most cases.
Cannot be used with a beforeRequest callback to redirect proxied traffic; return a url from the callback instead.
Removed type alias; use TlsHandshakeFailure instead.
Removed option; use additionalTrustedCAs instead.
The string format in the trustedCAs proxy settings option for upstream proxying has been removed.
The 503 response for websocket connections that match no rules now has different content to better match the HTTP request equivalent.
Step definitions are exported as webSocketSteps; implementations are no longer exported and Handler names have been replaced with Step names.
New APIs and options 11
Adds a non-final rule step that waits the specified milliseconds before the next step runs.
Provides the tunnel target hostname and port for TLS events and the calculated destination for request events.
Adds regex-based host matching and replacement to request transform options.
Adds regex-based path matching and replacement to request transform options.
Adds regex-based query matching and replacement to request transform options.
The Mockttp client option value
nonedisables automatic decoding, exposing encoded data and requiring manual handling.Enables blind passthrough of unknown-protocol traffic when a connection destination is provided through an HTTP or SOCKS tunnel.
Adds events exposing all proxied unknown-protocol passthrough data.
Adds protocol rewriting to request transform options for HTTP requests and websockets.
Enables inbound SOCKS proxying with the
socks: trueoption.Request events and similar events now expose connection tags attached through proxy authentication metadata.
Fixes and other changes 1
When passthrough options modify a proxied request body, valid framing headers are enforced and set if missing.
mockttp 333 changes
Breaking changes 25
The body property was removed from aborted request event data because it was always empty.
The admin server's activeServerPorts method was removed.
The deprecated method was removed; use addRequestRules instead.
The synchronous body decoder was removed; use the asynchronous body.getDecodedBuffer() method instead.
The synchronous body decoder was removed; use the asynchronous body.getFormData() method instead.
The synchronous body decoder was removed; use the asynchronous body.getJson() method instead.
The synchronous body decoder was removed; use the asynchronous body.getText() method instead.
Callback results with body or json are automatically encoded to match the content-encoding header; return rawBody as a Buffer or Uint8Array to bypass encoding.
The deprecated root export was removed; use requestHandlers instead.
The deprecated passthrough rule option was removed; use ignoreHostHttpsErrors instead.
This event was replaced by mock-session-started.
This event was replaced by mock-session-stopping.
The deprecated root export was removed; use RequestRuleData instead.
The old rule definition method was removed; use mockServer.forAnyRequest() instead.
The old rule definition method was removed; use the equivalent forX method, such as mockServer.forGet().
The old rule definition method was removed; use the equivalent forX method, such as mockServer.forPost().
The standalone server reference was replaced with Mockttp.getAdminServer().
Node.js v12 is no longer supported; the minimum supported version is v14.14.0.
Event subscriptions are reset when a Mockttp instance resets, stops, or starts.
Added a priority field for rules, including priority: 0 as the replacement for setFallbackRule.
The method was removed; set rules with the new priority: 0 field instead.
The deprecated method was removed; use setRequestRules instead.
The deprecated request rule builder method was removed; use thenJson instead.
The deprecated instance subscription event was removed; use tls-client-error instead.
Unmatched incoming websockets now receive a 503 instead of being automatically proxied; define an explicit forAnyWebSocket().thenPassThrough() rule to proxy them.
New APIs and options 7
Added a way to define multiple custom layers of rules at different priorities.
Added a matcher for more precise host matching.
Added a matcher for more precise host matching.
Added support for multiple fallback rules and using matchers on fallback rules.
Exposed requests and responses now include a lowercased header object with single-string or array-of-string values.
Exposed requests and responses now include rawHeader, preserving received header order and casing.
Added a method to reject websocket connections with a given HTTP response.
Behavior and default changes 1
Passthrough traffic preserves exact header formatting where possible; transform objects and callbacks normalize header names and may change order.
mockttp 28 changes
Breaking changes 5
Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead.
Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead.
Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead.
Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead.
Node v10 is no longer officially supported or tested, though it still works for now and may stop working without warning in future versions.
New APIs and options 3
Enables chaining mockttp with upstream proxies using passthrough rules.
Automatically transform proxied content by replacing or updating most properties, instead of using a custom beforeRequest callback for common cases.
Automatically transform proxied content by replacing or updating most properties, instead of using a custom beforeResponse callback for common cases.