mockttp
    Preparing search index...

    Interface MockttpServer

    A in-process Mockttp implementation. This starts servers on the local machine in the current process, and exposes methods to directly manage them.

    This class does not work in browsers, as it expects to be able to start HTTP servers.

    interface MockttpServer {
        get port(): number;
        get proxyEnv(): ProxyEnvConfig;
        get url(): string;
        addRequestRule(rule: RequestRuleData): Promise<MockedEndpoint>;
        addRequestRules(
            ...ruleData: RequestRuleData[],
        ): Promise<ServerMockedEndpoint[]>;
        addWebSocketRule(rule: WebSocketRuleData): Promise<MockedEndpoint>;
        addWebSocketRules(
            ...ruleData: WebSocketRuleData[],
        ): Promise<ServerMockedEndpoint[]>;
        enableDebug(): void;
        forAnyRequest(): RequestRuleBuilder;
        forAnyWebSocket(url?: string | RegExp): WebSocketRuleBuilder;
        forDelete(url?: string | RegExp): RequestRuleBuilder;
        forGet(url?: string | RegExp): RequestRuleBuilder;
        forHead(url?: string | RegExp): RequestRuleBuilder;
        forJsonRpcRequest(
            match?: { method?: string; params?: any },
        ): RequestRuleBuilder;
        forOptions(url?: string | RegExp): RequestRuleBuilder;
        forPatch(url?: string | RegExp): RequestRuleBuilder;
        forPost(url?: string | RegExp): RequestRuleBuilder;
        forPut(url?: string | RegExp): RequestRuleBuilder;
        forQuery(url?: string | RegExp): RequestRuleBuilder;
        forTrace(url?: string | RegExp): RequestRuleBuilder;
        forUnmatchedRequest(): RequestRuleBuilder;
        getMockedEndpoints(): Promise<ServerMockedEndpoint[]>;
        getPendingEndpoints(): Promise<ServerMockedEndpoint[]>;
        getRuleParameterKeys(): Promise<never[]>;
        listenerCount(event: string, listener?: (...args: any[]) => void): number;
        on(
            event: "request-initiated",
            callback: (req: Request) => void,
        ): Promise<void>;
        on(
            event: "request-body-data",
            callback: (req: BodyData) => void,
        ): Promise<void>;
        on(
            event: "request",
            callback: (req: CompletedRequest) => void,
        ): Promise<void>;
        on(
            event: "response-initiated",
            callback: (req: InitiatedResponse) => void,
        ): Promise<void>;
        on(
            event: "response-information",
            callback: (info: InformationalResponse) => void,
        ): Promise<void>;
        on(
            event: "response-body-data",
            callback: (req: BodyData) => void,
        ): Promise<void>;
        on(
            event: "response",
            callback: (req: CompletedResponse) => void,
        ): Promise<void>;
        on(event: "abort", callback: (req: Request) => void): Promise<void>;
        on(
            event: "websocket-request",
            callback: (req: CompletedRequest) => void,
        ): Promise<void>;
        on(
            event: "websocket-accepted",
            callback: (req: CompletedResponse) => void,
        ): Promise<void>;
        on(
            event: "websocket-message-received",
            callback: (req: WebSocketMessage) => void,
        ): Promise<void>;
        on(
            event: "websocket-message-sent",
            callback: (req: WebSocketMessage) => void,
        ): Promise<void>;
        on(
            event: "websocket-close",
            callback: (close: WebSocketClose) => void,
        ): Promise<void>;
        on(
            event: "tls-passthrough-opened",
            callback: (req: TlsPassthroughEvent) => void,
        ): Promise<void>;
        on(
            event: "tls-passthrough-closed",
            callback: (req: TlsPassthroughEvent) => void,
        ): Promise<void>;
        on(
            event: "tls-client-error",
            callback: (req: TlsHandshakeFailure) => void,
        ): Promise<void>;
        on(
            event: "client-error",
            callback: (error: ClientError) => void,
        ): Promise<void>;
        on(
            event: "raw-passthrough-opened",
            callback: (req: RawPassthroughEvent) => void,
        ): Promise<void>;
        on(
            event: "raw-passthrough-closed",
            callback: (req: RawPassthroughEvent) => void,
        ): Promise<void>;
        on(
            event: "raw-passthrough-data",
            callback: (req: RawPassthroughDataEvent) => void,
        ): Promise<void>;
        on<T = unknown>(
            event: "rule-event",
            callback: (event: RuleEvent<T>) => void,
        ): Promise<void>;
        reset(): void;
        setRequestRules(
            ...ruleData: RequestRuleData[],
        ): Promise<ServerMockedEndpoint[]>;
        setWebSocketRules(
            ...ruleData: WebSocketRuleData[],
        ): Promise<ServerMockedEndpoint[]>;
        start(portParam?: number | PortRange): Promise<void>;
        stop(): Promise<void>;
        urlFor(path: string): string;
    }

    Hierarchy

    • AbstractMockttp
      • MockttpServer

    Implements

    Index
    on
    port getMockedEndpoints getPendingEndpoints getRuleParameterKeys
    proxyEnv url addRequestRule addRequestRules addWebSocketRule addWebSocketRules forAnyRequest forAnyWebSocket forDelete forGet forHead forJsonRpcRequest forOptions forPatch forPost forPut forQuery forTrace forUnmatchedRequest listenerCount setRequestRules setWebSocketRules urlFor
    enableDebug reset start stop

    • Parameters

      • event: "request-initiated"
      • callback: (req: Request) => void

      Returns Promise<void>

    • Subscribe to hear about request body data live, streaming in progressive chunks as it's received (listen for request if you just want to receive the complete body once it's done).

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      • event: "request-body-data"
      • callback: (req: BodyData) => void

      Returns Promise<void>

    • Subscribe to hear about request details once the request is fully received.

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about response details as soon as the initial response (the status code & headers) are sent, without waiting for the body.

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about HTTP 1xx informational responses (e.g. 102 Processing, 103 Early Hints) sent before the final response.

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about response body data live, streaming in progressive chunks as it's received (listen for response if you just want to receive the complete body once it's done).

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      • event: "response-body-data"
      • callback: (req: BodyData) => void

      Returns Promise<void>

    • Subscribe to hear about response details when the response is completed.

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about websocket connection requests. This event fires when the initial WebSocket request is completed, regardless of whether the request is accepted.

      This is only useful in some niche use cases, such as logging all websockets seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      • event: "abort"
      • callback: (req: Request) => void

      Returns Promise<void>

    • Subscribe to hear about websocket connection upgrades. This event fires when a WebSocket request is accepted, returning the HTTP response body that was sent before the WebSocket stream starts.

      This is only useful in some niche use cases, such as logging all websockets seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about websocket messages received by Mockttp from its downstream websocket clients. This event fires whenever any data is received on an open mocked WebSocket.

      This is only useful in some niche use cases, such as logging all websockets seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about websocket messages sent by Mockttp to its downstream websocket clients. This event fires whenever any data is sent on an open mocked WebSocket.

      This is only useful in some niche use cases, such as logging all websockets seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear when a websocket connection is closed. This fires only for clean websocket shutdowns, after the websocket was initially accepted. If the connection is closed uncleanly, an 'abort' event will fire instead. If the websocket was initially rejected explicitly, a 'response' event (with the rejecting response) will fire instead.

      This is only useful in some niche use cases, such as logging all websockets seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about requests that are aborted before the request or response is fully completed.

      This is only useful in some niche use cases, such as logging all requests seen by the server independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about TLS connections that are passed through the proxy without interception, due to the tlsPassthrough HTTPS option.

      This is only useful in some niche use cases, such as logging all requests seen by the server, independently of the rules defined.

      The callback will be called asynchronously from connection handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about closure of TLS connections that were passed through the proxy without interception, due to the tlsPassthrough HTTPS option.

      This is only useful in some niche use cases, such as logging all requests seen by the server, independently of the rules defined.

      The callback will be called asynchronously from connection handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about requests that start a TLS handshake, but fail to complete it. Not all clients report TLS errors explicitly, so this event fires for explicitly reported TLS errors, and for TLS connections that are immediately closed with no data sent.

      This is typically useful to detect clients who aren't correctly configured to trust the configured HTTPS certificate. The callback is given the host name provided by the client via SNI, if SNI was used (it almost always is).

      This is only useful in some niche use cases, such as logging all requests seen by the server, independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about requests that fail before successfully sending their initial parameters (the request line & headers). This will fire for requests that drop connections early, send invalid or too-long headers, or aren't correctly parseable in some form.

      This is typically useful to detect clients who aren't correctly configured. The callback is given an object containing the request (as we were best able to parse it) and either the error response returned, or 'aborted' if the connection was disconnected before the server could respond.

      This is only useful in some niche use cases, such as logging all requests seen by the server, independently of the rules defined.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Parameters

      • event: "client-error"
      • callback: (error: ClientError) => void

      Returns Promise<void>

    • Subscribe to hear about connections that are passed through the proxy without interception, due to the passthrough option.

      This is separate to TLS passthrough: raw passthrough happens automatically before any TLS handshake is received (so includes no TLS data, and may use any protocol) generally because the protocol on the connection is not HTTP. TLS passthrough happens after the TLS client hello has been received, only if it has matched a rule defined in the tlsPassthrough options (e.g. a specific hostname).

      Parameters

      Returns Promise<void>

    • Subscribe to hear about close of connections that are passed through the proxy without interception, due to the passthrough option. See raw-passthrough-opened for more details.

      Parameters

      Returns Promise<void>

    • Subscribe to hear about each chunk of data that is passed through the raw passthrough non-intercepted tunnels, due to the passthrough option. See raw-passthrough-opened for more details.

      Parameters

      Returns Promise<void>

    • Some rules may emit events with metadata about request processing. For example, passthrough rules may emit events about upstream server interactions.

      You can listen to rule-event to hear about all these events. When emitted, this will include the id of the request being processed, the id of the rule that fired the event, the type of the event, and the event data itself.

      This is only useful in some niche use cases, such as logging all proxied upstream requests made by the server, separately from the client connections handled.

      The callback will be called asynchronously from request handling. This function returns a promise, and the callback is not guaranteed to be registered until the promise is resolved.

      Type Parameters

      • T = unknown

      Parameters

      • event: "rule-event"
      • callback: (event: RuleEvent<T>) => void

      Returns Promise<void>

    • get port(): number

      The port the server is running on.

      This will throw an error if read before the server is started.

      Returns number

    • Returns the set of registered but pending mock endpoints: endpoints which either haven't seen the specified number of requests (if one was specified e.g. with .twice()) or which haven't seen at least one request, by default.

      Returns Promise<ServerMockedEndpoint[]>

    • List the names of the rule parameters available for rule definitions. These parameters are defined by the admin server. This list can be used in some advanced use cases to confirm beforehand that the parameters a client wishes to reference are available.

      Only relevant to remote/browser Mockttp usage. Servers created directly without any admin server will never have rule parameters defined, and so this method will always return an empty list.

      Returns Promise<never[]>

    • Parameters

      • match: { method?: string; params?: any } = {}

      Returns RequestRuleBuilder

    • Parameters

      • event: string
      • Optionallistener: (...args: any[]) => void

      Returns number

    • Parameters

      • path: string

      Returns string

    • Enable extra debug output so you can understand exactly what the server is doing.

      Returns void

    • Reset the stored rules and subscriptions. Most of the time it's better to start & stop the server instead, but this can be useful in some special cases.

      Returns void

    • Start a mock server.

      Specify a fixed port if you need one.

      If you don't, a random port will be chosen, which you can get later with .port, or by using .url and .urlFor(path) to generate your URLs automatically.

      If you need to allow port selection, but in a specific range, pass a { startPort, endPort } pair to define the allowed (inclusive) range.

      Parameters

      Returns Promise<void>

    • Stop the mock server and reset all rules and subscriptions.

      Returns Promise<void>

    Settings
    Member Visibility

    On This Page
    Events
    Metadata
    Other
    Setup