Mockttp HTTP Mocking Server

Common errors

• TypeError: mockttp.getLocal is not a function

  cause Attempting to use `require('mockttp').getLocal()` in an environment where Mockttp is primarily detected as an ES module or when using incorrect CommonJS import syntax.
  fix Ensure you are using the correct import style for your module system: `import { getLocal } from 'mockttp';` for ESM, or `const mockttp = require('mockttp'); const server = mockttp.getLocal();` for CJS.

• TypeError: server.get is not a function

  cause Using the deprecated `get()` method (or `post()`, `anyRequest()`) on the mock server instance, which was removed in v3.0.0.
  fix Update your code to use the modern, explicit rule definition methods: `server.forGet()`, `server.forPost()`, `server.forAnyRequest()`, etc.

• The 'mockttp' package requires Node.js version >=20.0.0.

  cause Your Node.js environment version is older than the minimum required by Mockttp v4.x.x.
  fix Upgrade your Node.js installation to version 20.0.0 or newer. Use a Node Version Manager (like nvm) to easily switch versions.

• Error: self signed certificate in certificate chain

  cause Your client is not trusting the self-signed HTTPS certificate generated by Mockttp when it's intercepting secure traffic.
  fix Configure your HTTP client (e.g., `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'` for Node.js, or add the generated CA certificate to your client's trust store) or operating system to explicitly trust Mockttp's CA certificate.

Warnings

• breaking Mockttp v4.0.0 and above require Node.js v20.0.0 or higher. Running on older Node.js versions will result in an error.
  Fix: Upgrade your Node.js environment to version 20.0.0 or newer. Consider using nvm or similar tools for managing Node.js versions.
• breaking With the release of v3.0.0, Mockttp dropped support for Node.js v12. The new minimum Node.js version is v14.14.0.
  Fix: Ensure your Node.js environment is at least v14.14.0. Upgrade if you are on an unsupported version.
• breaking All rule definition methods that did not start with `.for[...]()` (e.g., `mockServer.get()`, `mockServer.post()`, `mockServer.anyRequest()`) were removed in v3.0.0. These were deprecated in v2.5.0.
  Fix: Replace old methods with their `.forX()` equivalents, such as `mockServer.forGet()`, `mockServer.forPost()`, or `mockServer.forAnyRequest()`.
• breaking Asynchronous body decoding is required for some content encodings (e.g., Brotli, Zstandard) since v2.0.0. Using synchronous properties like `body.decodedBuffer`, `body.text`, `body.json`, or `body.formData` may no longer decode content correctly or efficiently.
  Fix: Switch to the corresponding asynchronous `body.getX()` methods (e.g., `body.getDecodedBuffer()`, `body.getText()`, `body.getJson()`, `body.getFormData()`) for all content decoding.
• gotcha When intercepting HTTPS traffic, Mockttp generates a self-signed CA certificate. For your client (e.g., browser, `fetch`, `axios`) to trust the intercepted traffic, you must explicitly configure it to trust this generated certificate.
  Fix: Pass the generated `https` configuration to the mock server, and configure your HTTP client or operating system to trust the CA certificate provided by `mockttp.generateCACertificate()` or `server.port` / `server.url`.

Install

• npm install mockttp npm
• yarn add mockttp yarn
• pnpm add mockttp pnpm

Imports

• * as mockttp
  wrong:

  const mockttp = require('mockttp');

  correct:

  import * as mockttp from 'mockttp';

  This is the standard ESM import for the entire library. For CJS, use `const mockttp = require('mockttp');` to access all exports. Named exports are generally preferred for tree-shaking and clarity.
• { getLocal, getRemote }
  wrong:

  import mockttp, { getLocal } from 'mockttp';

  correct:

  import { getLocal, getRemote } from 'mockttp';

  Preferred way to import specific server constructors in ESM environments. Mockttp does not provide a default export.
• getLocal
  wrong:

  const { getLocal } = require('mockttp');

  correct:

  const mockServer = require('mockttp').getLocal();

  CommonJS pattern to instantiate a local mock server. While `{ getLocal } = require('mockttp');` also works, accessing directly from the full export is frequently seen in CJS examples.

Quickstart

Demonstrates setting up a local Mockttp server with HTTPS, defining a POST rule with a delay and a WebSocket passthrough rule with request transformation, and starting the server.

import * as mockttp from 'mockttp';

async function runMockServer() {
  // Generate a CA certificate for HTTPS interception if needed
  // In a real test, you'd configure your client to trust this CA.
  const https = await mockttp.generateCACertificate();
  const server = mockttp.getLocal({ https });

  // Define a rule for a POST request to example.com
  server.forPost()
    .forHostname("example.com")
    .delay(500) // Introduce a 500ms delay
    .thenReply(200, "Hello world from Mockttp!");

  // Define a rule for any WebSocket connection with a specific cookie
  server.forAnyWebSocket()
    .withHeaders({ cookie: 'abcd' })
    .thenPassThrough({
      transformRequest: {
        matchReplaceQuery: [/username=(.*)/, 'role=admin&username=$1']
      }
    });

  await server.start();
  console.log(`Mock server started on port ${server.port}`);
  console.log('Intercepting example.com POST requests and transforming WebSockets.');

  // In a real application, you'd now run your client code that makes requests.
  // For demonstration, we'll keep the server running for a bit.
  setTimeout(async () => {
    await server.stop();
    console.log('Mock server stopped.');
  }, 10000);
}

runMockServer().catch(console.error);