mockttp

Mockttp provides three primary ways to instantiate a client, depending on your environment and whether the mock server is running in-process or remotely:

• getLocal(): Returns a Mockttp instance using a local in-process mock server. In Node.js, this automatically manages server lifecycle. In a browser, this is an alias for getRemote().
• getRemote(): Returns a Mockttp instance that communicates with a separate admin server to configure a remote mock server. This is required for browser-based testing (since browsers cannot host HTTP servers) and is useful for testing mobile/IoT devices on a network.
• getAdminServer(): Returns an admin server (Node.js only) that allows remote clients to start, stop, and configure multiple mock servers. You can run this via the CLI helper mockttp -c [test command] to automate lifecycle management.

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

To perform an HTTP integration test, follow these steps:

1. Start a Mockttp server using mockttp.getLocal().
2. Define mocks for specific endpoints using .forMethod(path).thenReply(...).
3. Execute real HTTP requests against the server or through the proxy.
4. Assert on the responses or inspect the requests received by the server.

This workflow works in both Node.js and modern browsers.

const superagent = require("superagent");
const mockServer = require("mockttp").getLocal();

describe("Mockttp", () => {
    // Start your mock server
    beforeEach(() => mockServer.start(8080));
    afterEach(() => mockServer.stop());

    it("lets you mock requests, and assert on the results", async () => {
        // Mock your endpoints
        await mockServer.forGet("/mocked-path").thenReply(200, "A mocked response");

        // Make a request
        const response = await superagent.get("http://localhost:8080/mocked-path");

        // Assert on the results
        expect(response.text).to.equal("A mocked response");
    });
});

To mock HTTPS, you must generate a CA certificate, provide it to Mockttp, and ensure your HTTP client trusts it.

1. Generate a certificate using OpenSSL:

openssl req -x509 -new -nodes -keyout testCA.key -sha256 -days 365 -out testCA.pem -subj '/CN=Mockttp Testing CA - DO NOT TRUST'

2. Pass the certificate to Mockttp during setup using the https option:

const mockServer = getLocal({
    https: {
        keyPath: './testCA.key',
        certPath: './testCA.pem'
    }
});

3. Trust the certificate in your client:

• Node.js: Set the NODE_EXTRA_CA_CERTS environment variable to the path of your .pem certificate.
• Chrome: Use the --ignore-certificate-errors-spki-list=<spki fingerprint> flag. To get the fingerprint, run: openssl x509 -in testCA.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
• Firefox: Manually add the certificate as a CA in a dedicated test profile.

The RequestRuleBuilder is a fluent API used to define how Mockttp should intercept and handle specific HTTP requests.

Workflow:

1. Initiate: Start a builder from a Mockttp instance using methods like .forGet(path), .forPost(path), or similar. This defines the initial matching criteria (Method and Path).
2. Configure: Chain methods to add more precise matching behavior, add delays, or register webhooks.
3. Handle: Use terminal methods (starting with then...) to define the response or action (e.g., thenReply, thenJson, thenCallback).
4. Register: The terminal methods return a Promise<MockedEndpoint>. You must await this promise to ensure the rule is fully registered with the server before sending requests to it. The returned MockedEndpoint can be used to assert on the requests that match the rule.

Note: You should never instantiate RequestRuleBuilder directly; always use the Mockttp instance.

// Example workflow
const endpoint = await mockttpInstance
  .forGet('/api/user')
  .delay(100)
  .thenJson(200, { id: 1, name: 'John Doe' });

// Now the rule is active and 'endpoint' can be used for assertions

A ProxySettingSource allows you to determine the proxy configuration dynamically. It can be one of the following:

1. A fixed ProxySetting object.
2. A ProxySettingCallback: A function that receives ProxySettingCallbackParams (containing the hostname) and returns a ProxySetting or undefined.
3. An Array<ProxySettingSource>: An array of sources that are evaluated in order. The first source that returns a valid ProxySetting is used.
4. undefined.

type ProxySettingCallbackParams = { hostname: string };
type ProxySettingCallback = (params: ProxySettingCallbackParams) => Promise<ProxySetting | undefined> | ProxySetting | undefined;

// Example of a dynamic callback
const dynamicSource: ProxySettingCallback = async ({ hostname }) => {
  if (hostname.endsWith('.internal.com')) {
    return { proxyUrl: 'http://internal-proxy:8080' };
  }
  return undefined;
};

Mockttp allows you to define a sequence of actions (steps) that occur when a request matches a rule. These steps are implemented via classes that implement the RequestStepDefinition interface. Steps can be terminal (ending the request lifecycle) or non-terminal (allowing subsequent steps to execute).

Common step types include:

• Terminal Steps: CloseConnectionStep, ResetConnectionStep, TimeoutStep, and JsonRpcResponseStep (when providing a final result/error).
• Non-Terminal Steps: DelayStep, InformationalResponseStep, WaitForRequestBodyStep, and WebhookStep.

You can use the StepDefinitionLookup to identify available step types by their string identifiers.

import { StepDefinitionLookup } from 'mockttp';

// Example of the types of steps available via lookup
// 'simple', 'callback', 'stream', 'file', 'passthrough', 'close-connection', 
// 'reset-connection', 'timeout', 'json-rpc-response', 'delay', 
// 'wait-for-request-body', 'webhook', 'informational-response'