# What changed in mockttp

> 84 changes in mockttp 2 to 4 from its official release notes, upgrade guides and advisories: 61 breaking, 21 new APIs and options. Each one cited. Sources checked 2026-10-25. HTML: https://unstale.sh/npm/mockttp/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## mockttp 4

### Breaking changes

- Removed from TLS events because its meaning was ambiguous; use event.destination or event.tlsMetadata.sniHostname depending on the use case. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Removed from TLS events because its meaning was ambiguous; use event.destination for the tunnel target. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Provides the servername specified in the TLS SNI extension as an alternative to the removed TLS event properties. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- The passthrough rules forwarding option has moved into transformRequest URL rewriting options; simple cases can use replaceHost. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Subject-related options have moved into a separate subject options field. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Generated CA certificate key PEMs now use PKCS#8 format instead of PKCS#1. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- A modern Mockttp client controlling an old Mockttp server may have issues; a v4 client controlling any previous Mockttp version is unsupported. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Manual rule definitions now use steps instead of a single handler field. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Removed from TLS, request, and websocket events; use event.url, event.destination, or the appropriate host header instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Removed type alias; use CertDataOptions instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Removed type alias; use CertPathOptions instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- The minimum Node version is now 20; Node 18 may continue to work for now but may stop working unpredictably in a future release. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- 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. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Proxy-connection and proxy-authorization headers are now preprocessed and stripped before events, including for direct requests. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Proxy-connection and proxy-authorization headers are now preprocessed and stripped before events, including for direct requests. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Explicitly proxied destinations now take precedence over mismatching host or :authority header values, including in the url property. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Only real RegExp instances are treated as regular expressions; regex-compatible objects are no longer accepted. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- 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. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Adds host rewriting to request transform options for HTTP requests and websockets. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Step definitions are exported as requestSteps; implementations are no longer exported and Handler names have been replaced with Step names. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Renamed to FixedResponseHandler. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Renamed to FlexiblePathMatcher. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Upstream ECONNRESET errors are simulated downstream only when this option is set. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- The callback result field was removed; use statusCode instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Manual rule handlers are now steps and can be multiple; replace handler: X with steps: [X] in most cases. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Cannot be used with a beforeRequest callback to redirect proxied traffic; return a url from the callback instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Removed type alias; use TlsHandshakeFailure instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Removed option; use additionalTrustedCAs instead. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- The string format in the trustedCAs proxy settings option for upstream proxying has been removed. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- The 503 response for websocket connections that match no rules now has different content to better match the HTTP request equivalent. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Step definitions are exported as webSocketSteps; implementations are no longer exported and Handler names have been replaced with Step names. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)

### New APIs and options

- Adds a non-final rule step that waits the specified milliseconds before the next step runs. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Provides the tunnel target hostname and port for TLS events and the calculated destination for request events. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Adds regex-based host matching and replacement to request transform options. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Adds regex-based path matching and replacement to request transform options. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Adds regex-based query matching and replacement to request transform options. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- The Mockttp client option value `none` disables automatic decoding, exposing encoded data and requiring manual handling. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Enables blind passthrough of unknown-protocol traffic when a connection destination is provided through an HTTP or SOCKS tunnel. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Adds events exposing all proxied unknown-protocol passthrough data. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Adds protocol rewriting to request transform options for HTTP requests and websockets. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Enables inbound SOCKS proxying with the `socks: true` option. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
- Request events and similar events now expose connection tags attached through proxy authentication metadata. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)

### Fixes and other changes

- When passthrough options modify a proxied request body, valid framing headers are enforced and set if missing. (4.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)

## mockttp 3

### Breaking changes

- The body property was removed from aborted request event data because it was always empty. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The admin server's activeServerPorts method was removed. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated method was removed; use addRequestRules instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The synchronous body decoder was removed; use the asynchronous body.getDecodedBuffer() method instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The synchronous body decoder was removed; use the asynchronous body.getFormData() method instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The synchronous body decoder was removed; use the asynchronous body.getJson() method instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The synchronous body decoder was removed; use the asynchronous body.getText() method instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- 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. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated root export was removed; use requestHandlers instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated passthrough rule option was removed; use ignoreHostHttpsErrors instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- This event was replaced by mock-session-started. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- This event was replaced by mock-session-stopping. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated root export was removed; use RequestRuleData instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The old rule definition method was removed; use mockServer.forAnyRequest() instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The old rule definition method was removed; use the equivalent forX method, such as mockServer.forGet(). (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The old rule definition method was removed; use the equivalent forX method, such as mockServer.forPost(). (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The standalone server reference was replaced with Mockttp.getAdminServer(). (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Node.js v12 is no longer supported; the minimum supported version is v14.14.0. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Event subscriptions are reset when a Mockttp instance resets, stops, or starts. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Added a priority field for rules, including priority: 0 as the replacement for setFallbackRule. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The method was removed; set rules with the new priority: 0 field instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated method was removed; use setRequestRules instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated request rule builder method was removed; use thenJson instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- The deprecated instance subscription event was removed; use tls-client-error instead. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Unmatched incoming websockets now receive a 503 instead of being automatically proxied; define an explicit forAnyWebSocket().thenPassThrough() rule to proxy them. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)

### New APIs and options

- Added a way to define multiple custom layers of rules at different priorities. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Added a matcher for more precise host matching. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Added a matcher for more precise host matching. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Added support for multiple fallback rules and using matchers on fallback rules. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Exposed requests and responses now include a lowercased header object with single-string or array-of-string values. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Exposed requests and responses now include rawHeader, preserving received header order and casing. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)
- Added a method to reject websocket connections with a given HTTP response. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)

### Behavior and default changes

- Passthrough traffic preserves exact header formatting where possible; transform objects and callbacks normalize header names and may change order. (3.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v3.0.0)

## mockttp 2

### Breaking changes

- Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)
- Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)
- Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)
- Unusual content encodings such as Brotli are no longer handled automatically by this synchronous property; use the corresponding asynchronous body.getX() method instead. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)
- Node v10 is no longer officially supported or tested, though it still works for now and may stop working without warning in future versions. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)

### New APIs and options

- Enables chaining mockttp with upstream proxies using passthrough rules. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)
- Automatically transform proxied content by replacing or updating most properties, instead of using a custom beforeRequest callback for common cases. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)
- Automatically transform proxied content by replacing or updating most properties, instead of using a custom beforeResponse callback for common cases. (2.0.0) — [release notes](https://github.com/httptoolkit/mockttp/releases/tag/v2.0.0)