or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

certificate-management.mdevent-monitoring.mdhttp-request-mocking.mdindex.mdmock-server-setup.mdresponse-actions.mdwebsocket-mocking.md
tile.json

tessl/npm-mockttp

Mock HTTP server for testing HTTP clients and stubbing webservices

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/mockttp@4.1.x

To install, run

npx @tessl/cli install tessl/npm-mockttp@4.1.0

index.mddocs/

Mockttp

Mockttp is a comprehensive HTTP mocking and testing library that enables developers to intercept, transform, and test HTTP requests and responses in both Node.js and browser environments. It provides a robust solution for integration testing by allowing users to stub server responses, verify HTTP requests, and intercept HTTPS traffic with built-in self-signed certificate generation.

Package Information

  • Package Name: mockttp
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install mockttp

Core Imports

import { 
  getLocal, 
  getRemote, 
  getAdminServer, 
  RulePriority,
  generateCACertificate,
  generateSPKIFingerprint,
  matchers,
  requestSteps,
  webSocketSteps,
  completionCheckers,
  MOCKTTP_PARAM_REF,
  resetAdminServer
} from "mockttp";

// Import types
import type {
  Mockttp,
  MockttpOptions,
  MockttpHttpsOptions,
  MockttpClientOptions,
  MockttpAdminServerOptions,
  RequestRuleBuilder,
  WebSocketRuleBuilder,
  MockedEndpoint,
  CompletedRequest,
  CompletedResponse,
  Headers,
  Method,
  RequestRuleData,
  WebSocketRuleData,
  ProxyConfig,
  CAOptions,
  RuleParameterReference,
  RuleParameters
} from "mockttp";

For CommonJS:

const { 
  getLocal, 
  getRemote, 
  getAdminServer, 
  RulePriority,
  generateCACertificate,
  generateSPKIFingerprint,
  matchers,
  requestSteps,
  webSocketSteps,
  completionCheckers,
  MOCKTTP_PARAM_REF,
  resetAdminServer
} = require("mockttp");

Basic Usage

import { getLocal } from "mockttp";

// Create a local mock server
const mockServer = getLocal();

// Start the server
await mockServer.start();

// Create mock rules
await mockServer.forGet("/api/users").thenReply(200, [
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" }
]);

// Your tests make requests to mockServer.url
// The server will respond with the mocked data

// Clean up
await mockServer.stop();

Architecture

Mockttp is built around several key components:

  • Mock Server Instances: Local servers (getLocal()) for in-process mocking, remote clients (getRemote()) for browser/external usage, and admin servers (getAdminServer()) for coordinating multiple mock instances
  • Rule-Based Matching: Flexible request matching system using method, path, headers, body content, and custom matchers
  • Response Generation: Support for fixed responses, callbacks, streams, files, and request forwarding/passthrough
  • Event System: Comprehensive event monitoring for requests, responses, WebSockets, TLS connections, and errors
  • Certificate Management: Built-in CA certificate generation and HTTPS interception with configurable trust and passthrough rules
  • Cross-Platform Support: Works in Node.js with full HTTP/HTTPS proxy capabilities and in browsers via admin server coordination

Capabilities

Mock Server Setup

Core server lifecycle management, configuration, and metadata access. Essential for starting mock servers and configuring HTTPS, CORS, and proxy behavior.

function getLocal(options?: MockttpOptions): Mockttp;
function getRemote(options?: MockttpClientOptions): Mockttp;
function getAdminServer(options?: MockttpAdminServerOptions): MockttpAdminServer;

interface Mockttp {
  start(port?: number | PortRange): Promise<void>;
  stop(): Promise<void>;
  enableDebug(): void;
  reset(): void;
  readonly url: string;
  readonly port: number;
  readonly proxyEnv: ProxyEnvConfig;
  urlFor(path: string): string;
}

Mock Server Setup

HTTP Request Mocking

Fluent rule builder system for matching and mocking HTTP requests with comprehensive matching capabilities including method, path, headers, body content, and custom logic.

interface Mockttp {
  forAnyRequest(): RequestRuleBuilder;
  forGet(url?: string | RegExp): RequestRuleBuilder;
  forPost(url?: string | RegExp): RequestRuleBuilder;
  forPut(url?: string | RegExp): RequestRuleBuilder;
  forDelete(url?: string | RegExp): RequestRuleBuilder;
  forPatch(url?: string | RegExp): RequestRuleBuilder;
  forHead(url?: string | RegExp): RequestRuleBuilder;
  forOptions(url?: string | RegExp): RequestRuleBuilder;
  forJsonRpcRequest(match?: {method?: string, params?: any}): RequestRuleBuilder;
}

interface RequestRuleBuilder {
  withHeaders(headers: Headers): this;
  withBody(body: string | Buffer | object): this;
  withJsonBodyIncluding(body: object): this;
  once(): this;
  twice(): this;
  times(n: number): this;
}

HTTP Request Mocking

Response Actions

Comprehensive response generation system supporting fixed responses, dynamic callbacks, file streaming, request forwarding, and connection manipulation for simulating various server behaviors.

interface RequestRuleBuilder {
  thenReply(status: number, data?: string | Buffer | object, headers?: Headers, trailers?: Trailers): Promise<MockedEndpoint>;
  thenJson(status: number, data: object, headers?: Headers): Promise<MockedEndpoint>;
  thenCallback(callback: (request: CompletedRequest) => CallbackResponseResult): Promise<MockedEndpoint>;
  thenPassThrough(options?: PassThroughStepOptions): Promise<MockedEndpoint>;
  thenForwardTo(target: string, options?: PassThroughStepOptions): Promise<MockedEndpoint>;
  thenCloseConnection(): Promise<MockedEndpoint>;
  thenTimeout(): Promise<MockedEndpoint>;
}

Response Actions

WebSocket Mocking

WebSocket connection interception and mocking with support for message echoing, forwarding, and custom handling for testing real-time applications.

interface Mockttp {
  forAnyWebSocket(): WebSocketRuleBuilder;
}

interface WebSocketRuleBuilder {
  withPath(path: string | RegExp): this;
  withHeaders(headers: Headers): this;
  thenEcho(): Promise<MockedEndpoint>;
  thenPassThrough(options?: PassThroughWebSocketStepOptions): Promise<MockedEndpoint>;
  thenPassivelyListen(): Promise<MockedEndpoint>;
  thenRejectConnection(statusCode?: number, statusMessage?: string): Promise<MockedEndpoint>;
}

WebSocket Mocking

Event Monitoring

Comprehensive event system for monitoring all HTTP/WebSocket traffic, TLS connections, errors, and custom rule events to enable detailed testing and debugging.

interface Mockttp {
  on(event: 'request', callback: (req: CompletedRequest) => void): Promise<void>;
  on(event: 'response', callback: (res: CompletedResponse) => void): Promise<void>;
  on(event: 'websocket-message-received', callback: (msg: WebSocketMessage) => void): Promise<void>;
  on(event: 'websocket-message-sent', callback: (msg: WebSocketMessage) => void): Promise<void>;
  on(event: 'abort', callback: (req: AbortedRequest) => void): Promise<void>;
  on(event: 'tls-client-error', callback: (error: TlsHandshakeFailure) => void): Promise<void>;
  on(event: 'client-error', callback: (error: ClientError) => void): Promise<void>;
}

Event Monitoring

Certificate Management

TLS certificate generation and management utilities for HTTPS interception, including CA certificate creation and SPKI fingerprint generation.

function generateCACertificate(options?: CAOptions): Promise<{key: string, cert: string}>;
function generateSPKIFingerprint(certPem: string): Promise<string>;

interface CAOptions {
  keyLength?: number;
  commonName?: string;
  organizationName?: string;
  countryName?: string;
}

Certificate Management

Types

Core Configuration Types

interface MockttpOptions {
  cors?: boolean | cors.CorsOptions;
  debug?: boolean;
  https?: MockttpHttpsOptions;
  http2?: true | 'fallback' | false;
  socks?: boolean | SocksServerOptions;
  suggestChanges?: boolean;
  recordTraffic?: boolean;
  maxBodySize?: number;
}

interface MockttpHttpsOptions {
  ca?: string | Buffer;
  cert?: string | Buffer;
  key?: string | Buffer;
  certPath?: string;
  keyPath?: string;
  keyLength?: number;
  defaultDomain?: string;
  tlsPassthrough?: Array<{hostname: string}>;
  tlsInterceptOnly?: Array<{hostname: string}>;
  tlsServerOptions?: {
    minVersion?: 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
  };
}

type PortRange = { startPort: number, endPort: number };

interface ProxyEnvConfig {
  HTTP_PROXY: string;
  HTTPS_PROXY: string;
}

Request/Response Types

interface Headers {
  [key: string]: undefined | string | string[];
}

interface Trailers {
  [key: string]: undefined | string | string[];
}

type RawHeaders = Array<[key: string, value: string]>;
type RawTrailers = RawHeaders;

interface Destination {
  hostname: string;
  port: number;
}

interface CompletedRequest {
  id: string;
  matchedRuleId?: string;
  protocol: string;
  httpVersion: string;
  method: string;
  url: string;
  path: string;
  remoteIpAddress?: string;
  remotePort?: number;
  destination: Destination;
  headers: Headers;
  rawHeaders: RawHeaders;
  body: CompletedBody;
  rawTrailers: RawTrailers;
  trailers: Trailers;
  timingEvents: TimingEvents;
  tags: string[];
}

interface CompletedResponse {
  id: string;
  statusCode: number;
  statusMessage: string;
  headers: Headers;
  rawHeaders: RawHeaders;
  body: CompletedBody;
  rawTrailers: RawTrailers;
  trailers: Trailers;
  timingEvents: TimingEvents;
  tags: string[];
}

interface CompletedBody {
  buffer: Buffer;
  getDecodedBuffer(): Promise<Buffer | undefined>;
  getText(): Promise<string | undefined>;
  getJson(): Promise<object | undefined>;
  getFormData(): Promise<{[key: string]: string | string[] | undefined} | undefined>;
  getUrlEncodedFormData(): Promise<{[key: string]: string | string[] | undefined} | undefined>;
  getMultipartFormData(): Promise<Array<{name?: string, filename?: string, type?: string, data: Buffer}> | undefined>;
}

WebSocket Types

interface WebSocketMessage {
  streamId: string;
  direction: 'sent' | 'received';
  content: Uint8Array;
  isBinary: boolean;
  eventTimestamp: number;
  timingEvents: TimingEvents;
  tags: string[];
}

interface WebSocketClose {
  streamId: string;
  closeCode: number | undefined;
  closeReason: string;
  timingEvents: TimingEvents;
  tags: string[];
}

Endpoint Types

interface MockedEndpoint {
  id: string;
  getSeenRequests(): Promise<CompletedRequest[]>;
  isPending(): Promise<boolean>;
}

interface TimingEvents {
  startTime: number;
  startTimestamp: number;
  bodyReceivedTimestamp?: number;
  headersSentTimestamp?: number;
  responseSentTimestamp?: number;
  wsAcceptedTimestamp?: number;
  wsClosedTimestamp?: number;
  abortedTimestamp?: number;
}

Error Types

interface AbortedRequest extends CompletedRequest {
  error?: {
    name?: string;
    code?: string;
    message?: string;
    stack?: string;
  };
}

interface ClientError {
  errorCode?: string;
  request: Partial<CompletedRequest>;
  response: CompletedResponse | 'aborted';
}

interface TlsHandshakeFailure {
  failureCause: 'closed' | 'reset' | 'cert-rejected' | 'no-shared-cipher' | 'handshake-timeout' | 'unknown';
  remoteIpAddress?: string;
  remotePort?: number;
  timingEvents: TlsFailureTimingEvents;
  tags: string[];
}

Constants

enum Method {
  GET,
  POST,
  PUT,  
  DELETE,
  PATCH,
  HEAD,
  OPTIONS
}

enum RulePriority {
  FALLBACK = 0,
  DEFAULT = 1
}

const DEFAULT_ADMIN_SERVER_PORT = 45454;