Class MockttpAdminServer
Hierarchy (view full)
- AdminServer<{
http: MockttpAdminPlugin;
}>- MockttpAdminServer
Index
Constructors
constructor
- new
Mockttp Admin Server(options): MockttpAdminServer Parameters
- options: MockttpAdminServerOptions
Returns MockttpAdminServer
Methods
on
- on(event, listener): void
Parameters
- event: "mock-session-started"
- listener: ((plugins: {
http: MockttpAdminPlugin;
}, sessionId: string) => void)- (plugins, sessionId): void
Parameters
- plugins: {
http: MockttpAdminPlugin;
}http: MockttpAdminPlugin
- sessionId: string
Returns void
- plugins: {
Returns void
- on(event, listener): void
Subscribe to hear when a mock session is stopped. The listener is provided with +the state of all plugins that are about to be stopped. This can be used to log +mock session shutdown, add side-effects that run elsewhere at shutdown, or clean +up after sessions in other ways.
+This is run synchronously immediately before the session is shutdown, whilst all +its state is still available, and before remote clients have had any response to +their request. This is also run before shutdown when the admin server itself is +cleanly shutdown with
+adminServer.stop().Parameters
- event: "mock-session-stopping"
- listener: ((plugins: {
http: MockttpAdminPlugin;
}, sessionId: string) => void)- (plugins, sessionId): void
Parameters
- plugins: {
http: MockttpAdminPlugin;
}http: MockttpAdminPlugin
- sessionId: string
Returns void
- plugins: {
Returns void
reset
start
stop
Class MockttpAdminPlugin
Implements
Index
Constructors
constructor
- new
Mockttp Admin Plugin(): MockttpAdminPlugin Returns MockttpAdminPlugin
Methods
build
enable
get
- get
Mock Server(): MockttpServer Returns MockttpServer
reset
start
- start(__namedParameters): Promise<{
mockRoot: string;
port: number;
}> Parameters
- __namedParameters: MockttpPluginOptions
Returns Promise<{
mockRoot: string;
port: number;
}>
stop
Class 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.
+Hierarchy
- AbstractMockttp
- MockttpServer
Implements
Index
Events
on
- on(event, callback): Promise<void>
Subscribe to hear about request details as soon as the initial request details +(method, path & headers) are received, 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>
- on(event, callback): 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
- event: "request"
- callback: ((req: CompletedRequest) => void)
- (req): void
Parameters
- req: CompletedRequest
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "response"
- callback: ((req: CompletedResponse) => void)
- (req): void
Parameters
- req: CompletedResponse
Returns void
Returns Promise<void>
- on(event, callback): 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
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-request"
- callback: ((req: CompletedRequest) => void)
- (req): void
Parameters
- req: CompletedRequest
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-accepted"
- callback: ((req: CompletedResponse) => void)
- (req): void
Parameters
- req: CompletedResponse
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-message-received"
- callback: ((req: WebSocketMessage) => void)
- (req): void
Parameters
- req: WebSocketMessage
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-message-sent"
- callback: ((req: WebSocketMessage) => void)
- (req): void
Parameters
- req: WebSocketMessage
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-close"
- callback: ((close: WebSocketClose) => void)
- (close): void
Parameters
- close: WebSocketClose
Returns void
Returns Promise<void>
- on(event, callback): Promise<void>
Subscribe to hear about TLS connections that are passed through the proxy without +interception, due to the
+tlsPassthroughHTTPS 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
- event: "tls-passthrough-opened"
- callback: ((req: TlsPassthroughEvent) => void)
- (req): void
Parameters
- req: TlsPassthroughEvent
Returns void
Returns Promise<void>
- on(event, callback): Promise<void>
Subscribe to hear about closure of TLS connections that were passed through the +proxy without interception, due to the
+tlsPassthroughHTTPS 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
- event: "tls-passthrough-closed"
- callback: ((req: TlsPassthroughEvent) => void)
- (req): void
Parameters
- req: TlsPassthroughEvent
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "tls-client-error"
- callback: ((req: TlsRequest) => void)
- (req): void
Parameters
- req: TlsRequest
Returns void
Returns Promise<void>
- on(event, callback): 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)
- (error): void
Parameters
- error: ClientError
Returns void
Returns Promise<void>
- on<T>(event, callback): 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
Parameters
Returns Promise<void>
Manual rule definition
add
- add
Request Rule(rule): Promise<MockedEndpoint> Adds the given HTTP request rule to the server.
+This is a convenient alias for calling
+addRequestRuleswith one rule, +and extracting the first endpoint result.This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
- rule: RequestRuleData
Returns Promise<MockedEndpoint>
add
- add
Request Rules(...ruleData): Promise<ServerMockedEndpoint[]> Adds the given HTTP request rules to the server.
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: RequestRuleData[]
Returns Promise<ServerMockedEndpoint[]>
add
- add
Web Socket Rule(rule): Promise<MockedEndpoint> Adds the given websocket rule to the server.
+This is a convenient alias for calling
+addWebSocketRuleswith one rule, +and extracting the first endpoint result.This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
- rule: WebSocketRuleData
Returns Promise<MockedEndpoint>
add
- add
Web Socket Rules(...ruleData): Promise<ServerMockedEndpoint[]> Adds the given websocket rules to the server.
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: WebSocketRuleData[]
Returns Promise<ServerMockedEndpoint[]>
set
- set
Request Rules(...ruleData): Promise<ServerMockedEndpoint[]> Set the given HTTP request rules as the only request rules on the server, +replacing any existing rules (except websocket rules).
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: RequestRuleData[]
Returns Promise<ServerMockedEndpoint[]>
set
- set
Web Socket Rules(...ruleData): Promise<ServerMockedEndpoint[]> Set the given websocket rules as the only websocket rules on the server, +replacing all existing websocket rules (but leaving normal rules untouched).
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: WebSocketRuleData[]
Returns Promise<ServerMockedEndpoint[]>
Metadata
port
- get port(): number
The port the server is running on.
+This will throw an error if read before the server is started.
+Returns number
proxy
- get proxyEnv(): ProxyEnvConfig
The environment variables typically needed to use this server as a proxy, in a format you +can add to your environment straight away.
+This will throw an error if read before the server is started.
+
+ +process.env = Object.assign(process.env, mockServer.proxyEnv) +Returns ProxyEnvConfig
url
- get url(): string
The root URL of the server.
+This will throw an error if read before the server is started.
+Returns string
get
- get
Mocked Endpoints(): Promise<ServerMockedEndpoint[]> Returns the set of currently registered mock endpoints.
+Returns Promise<ServerMockedEndpoint[]>
get
- get
Pending Endpoints(): Promise<ServerMockedEndpoint[]> 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[]>
get
- get
Rule Parameter Keys(): Promise<never[]> 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[]>
url
Mock HTTP requests
for
- for
Any Request(): RequestRuleBuilder Get a builder for a mock rule that will match any requests on any path.
+This only matches traditional HTTP requests, not websockets, which are handled +separately. To match websockets, use
+.forAnyWebSocket().Returns RequestRuleBuilder
for
- for
Delete(url?): RequestRuleBuilder Get a builder for a mock rule that will match DELETE requests for the given path. +If no path is specified, this matches all DELETE requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Get(url?): RequestRuleBuilder Get a builder for a mock rule that will match GET requests for the given path. +If no path is specified, this matches all GET requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Head(url?): RequestRuleBuilder Get a builder for a mock rule that will match HEAD requests for the given path. +If no path is specified, this matches all HEAD requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Json Rpc Request(match?): RequestRuleBuilder Match JSON-RPC requests, optionally matching a given method and/or params.
+If no method or params are specified, this will match all JSON-RPC requests.
+Params are matched flexibly, using the same logic as .withJsonBodyIncluding(), +so only the included fields are checked and other extra fields are ignored
+Parameters
- match: {
method?: string;
params?: any;
} = {}Optionalmethod?: stringOptionalparams?: any
Returns RequestRuleBuilder
- match: {
for
- for
Options(url?): RequestRuleBuilder Get a builder for a mock rule that will match OPTIONS requests for the given path.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
This can only be used if the
+corsoption has been set to false.If cors is true (the default when using a remote client, e.g. in the browser), +then the mock server automatically handles OPTIONS requests to ensure requests +to the server are allowed by clients observing CORS rules.
+You can pass
+{cors: false}togetLocal/getRemoteto disable this behaviour, +but if you're testing in a browser you will need to ensure you mock all OPTIONS +requests appropriately so that the browser allows your other requests to be sent.Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Patch(url?): RequestRuleBuilder Get a builder for a mock rule that will match PATCH requests for the given path. +If no path is specified, this matches all PATCH requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Post(url?): RequestRuleBuilder Get a builder for a mock rule that will match POST requests for the given path. +If no path is specified, this matches all POST requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Put(url?): RequestRuleBuilder Get a builder for a mock rule that will match PUT requests for the given path. +If no path is specified, this matches all PUT requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Unmatched Request(): RequestRuleBuilder Get a builder for a fallback mock rule that will match any unmatched requests +on any path.
+Fallback rules act like any other rule, but they only match if there is no +existing normal rule that matches the request, or if all existing rules have +an explicit execution limit (like
+once()) that has been completed.Returns RequestRuleBuilder
Mock websockets
for
- for
Any Web Socket(): WebSocketRuleBuilder Get a builder for a mock rule that will match all websocket connections.
+Returns WebSocketRuleBuilder
Other
constructor
- new
Mockttp Server(options?): MockttpServer Parameters
- options: MockttpOptions = {}
Returns MockttpServer
Setup
enable
reset
start
- start(portParam?): Promise<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.urland.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
- portParam: number | PortRange = ...
Returns Promise<void>
stop
Class AdminClient<Plugins>
A bare admin server client. This is not intended for general use, but can be useful when +building admin server plugins to mock non-HTTP protocols and other advanced use cases.
+For normal usage of Mockttp, you should use Mockttp.getRemote() instead, to get a Mockttp
+remote client, which wraps this class with the full Mockttp API for mocking HTTP.
This is part of Mockttp's experimental 'pluggable admin' API. It may change +unpredictably, even in minor releases.
+Type Parameters
- Plugins extends {
[key: string]: AdminPlugin<any, any>;
}
Hierarchy
- EventEmitter
- AdminClient
Index
Constructors
Accessors
Methods
Constructors
constructor
- new
Admin Client<Plugins>(options?): AdminClient<Plugins> Type Parameters
- Plugins extends {
[key: string]: AdminPlugin<any, any>;
}
Parameters
- options: AdminClientOptions = {}
Returns AdminClient<Plugins>
- Plugins extends {
Accessors
admin
- get adminStream(): Duplex
Returns Duplex
metadata
- get metadata(): PluginClientResponsesMap<Plugins>
Returns PluginClientResponsesMap<Plugins>
schema
- get schema(): SchemaIntrospector
Returns SchemaIntrospector
Methods
enable
get
is
reset
send
- send
Queries<Queries>(...queries): Promise<{
[n in string | number | symbol]: Queries[n<n>] extends AdminQuery<any, R>
? R
: never
}> Type Parameters
- Queries extends AdminQuery<any, any>[]
Parameters
Rest...queries: [...Queries[]]
Returns Promise<{
[n in string | number | symbol]: Queries[n<n>] extends AdminQuery<any, R>
? R
: never
}>
send
start
- start(pluginStartParams): Promise<PluginClientResponsesMap<Plugins>>
Parameters
- pluginStartParams: PluginStartParamsMap<Plugins>
Returns Promise<PluginClientResponsesMap<Plugins>>
stop
subscribe
Class AdminServer<Plugins>
Type Parameters
- Plugins extends {
[key: string]: AdminPlugin<any, any>;
}
Hierarchy (view full)
- AdminServer
Index
Constructors
constructor
- new
Admin Server<Plugins>(options?): AdminServer<Plugins> Type Parameters
- Plugins extends {
[key: string]: AdminPlugin<any, any>;
}
Parameters
- options: AdminServerOptions<Plugins> = {}
Returns AdminServer<Plugins>
- Plugins extends {
Methods
on
- on(event, listener): void
Subscribe to hear when each mock ession is started. The listener is provided the +session plugin data, which can be used to log session startup, add side-effects that +run elsewhere at startup, or preconfigure every started plugin in addition ways.
+This is run synchronously when a session is created, after it has fully started +but before its been returned to remote clients.
+Parameters
Returns void
- on(event, listener): void
Subscribe to hear when a mock session is stopped. The listener is provided with +the state of all plugins that are about to be stopped. This can be used to log +mock session shutdown, add side-effects that run elsewhere at shutdown, or clean +up after sessions in other ways.
+This is run synchronously immediately before the session is shutdown, whilst all +its state is still available, and before remote clients have had any response to +their request. This is also run before shutdown when the admin server itself is +cleanly shutdown with
+adminServer.stop().Parameters
Returns void
reset
start
stop
Class SchemaIntrospector
Index
Constructors
Methods
Constructors
constructor
- new
Schema Introspector(adminServerSchema): SchemaIntrospector Parameters
- adminServerSchema: any
Returns SchemaIntrospector
Class ClientServerChannel
Hierarchy
- Duplex
- ClientServerChannel
Index
Constructors
constructor
- new
Client Server Channel(rawStream, topicId?): ClientServerChannel Parameters
- rawStream: Duplex
OptionaltopicId: string
Returns ClientServerChannel
Methods
_read
_read
dispose
on
- on
Request<T, R>(cb): void Type Parameters
Parameters
- cb: ((request: T) => MaybePromise<R>)
- (request): MaybePromise<R>
Parameters
- request: T
Returns MaybePromise<R>
Returns void
- cb: ((request: T) => MaybePromise<R>)
- on
Request<T, R>(actionName, cb): void Type Parameters
Parameters
- actionName: string
- cb: ((request: T) => MaybePromise<R>)
- (request): MaybePromise<R>
Parameters
- request: T
Returns MaybePromise<R>
Returns void
request
Class SerializableAbstract
Hierarchy (view full)
- Serializable
- RequestMatcher
- WildcardMatcher
- MethodMatcher
- ProtocolMatcher
- HostMatcher
- HostnameMatcher
- PortMatcher
- SimplePathMatcher
- RegexPathMatcher
- RegexUrlMatcher
- HeaderMatcher
- ExactQueryMatcher
- QueryMatcher
- FormDataMatcher
- MultipartFormDataMatcher
- RawBodyMatcher
- RawBodyIncludesMatcher
- RegexBodyMatcher
- JsonBodyMatcher
- JsonBodyFlexibleMatcher
- CookieMatcher
- CallbackMatcher
- RequestHandlerDefinition
- SimpleHandlerDefinition
- CallbackHandlerDefinition
- StreamHandlerDefinition
- FileHandlerDefinition
- PassThroughHandlerDefinition
- CloseConnectionHandlerDefinition
- ResetConnectionHandlerDefinition
- TimeoutHandlerDefinition
- JsonRpcResponseHandlerDefinition
- WebSocketHandlerDefinition
- PassThroughWebSocketHandlerDefinition
- EchoWebSocketHandlerDefinition
- ListenWebSocketHandlerDefinition
- RejectWebSocketHandlerDefinition
- RuleCompletionChecker
- Always
- Once
- Twice
- Thrice
- NTimes
Index
Constructors
constructor
- new
Serializable(): Serializable Returns Serializable
Class RequestRule
Hierarchy (view full)
- Explainable
- RequestRule
Implements
Implemented by
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Request Rule(data): RequestRule Parameters
- data: RequestRuleData
Returns RequestRule
Methods
dispose
explain
handle
- handle(request, response, options): Promise<void>
Parameters
- request: OngoingRequest
- response: OngoingResponse
- options: {
emitEventCallback?: ((type: string, event: unknown) => void);
record: boolean;
}OptionalemitEvent Callback?: ((type: string, event: unknown) => void) - (type, event): void
Parameters
- type: string
- event: unknown
Returns void
record: boolean
Returns Promise<void>
- handle(req, res, options): Promise<void>
Parameters
- req: OngoingRequest
- res: OngoingResponse
- options: {
emitEventCallback?: ((type: string, event: unknown) => void);
record?: boolean;
}OptionalemitEvent Callback?: ((type: string, event: unknown) => void) - (type, event): void
Parameters
- type: string
- event: unknown
Returns void
Optionalrecord?: boolean
Returns Promise<void>
is
matches
- matches(request): MaybePromise<boolean>
Parameters
- request: OngoingRequest
Returns MaybePromise<boolean>
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class RequestRuleBuilder
RequestRuleBuilder
+A builder for defining mock rules. Create one using a method like
+.forGet(path) or .forPost(path) on a Mockttp instance, then call
+whatever methods you'd like here to define more precise request
+matching behaviour, control how the request is handled, and how
+many times this rule should be applied.
When you're done, call a .thenX() method to register the configured rule
+with the server. These return a promise for a MockedEndpoint, which can be
+used to verify the details of the requests matched by the rule.
This returns a promise because rule registration can be asynchronous,
+either when using a remote server or testing in the browser. Wait for the
+promise returned by .thenX() methods to guarantee that the rule has taken
+effect before sending requests to it.
Hierarchy
- BaseRuleBuilder
- RequestRuleBuilder
Index
Completion
Matching
Other
Responses
Matching
for
- for
Host(host): this Match only requests sent to the given host, i.e. the full hostname plus +port included in the request.
+This can behave somewhat confusingly when matching against the default +ports for a protocol (i.e. 80/443), or when specifying a hostname here +without specifying the port. In those cases it's usually better to use +forHostname and/or forPort instead to explicit match the content you're +interested in.
+Parameters
- host: string
Returns this
for
for
matching
- matching(content): this
Match only requests when the callback returns true
+Parameters
- content: ((request: CompletedRequest) => MaybePromise<boolean>)
- (request): MaybePromise<boolean>
Parameters
- request: CompletedRequest
Returns MaybePromise<boolean>
Returns this
- content: ((request: CompletedRequest) => MaybePromise<boolean>)
with
with
with
with
with
with
with
with
- with
Json Body Including(json): this Match only requests whose bodies match (contain equivalent +values, ignoring extra values) the given object, when +parsed as JSON. Matching behaviour is the same as Lodash's +_.isMatch method.
+Note that this only tests that the body can be parsed +as JSON - it doesn't require a content-type header.
+Parameters
- json: {}
Returns this
- json: {}
with
- with
Multipart Form(...matchConditions): this Match only requests whose bodies include the given multipart form data.
+This can take any number of form parts to look for. Each part is specified +with MultipartFieldMatchCondition object containing one or more of +
+name(string),filename(string) andcontent(string or buffer) as +fields to match against in the form data.Requests are matched if all conditions match at least one part in the +request's form data.
+Parameters
Rest...matchConditions: MultipartFieldMatchCondition[]
Returns this
with
with
with
Other
constructor
- new
Request Rule Builder(addRule): RequestRuleBuilder Mock rule builders should be constructed through the Mockttp instance you're +using, not directly. You shouldn't ever need to call this constructor.
+Parameters
- addRule: ((rule: RequestRuleData) => Promise<MockedEndpoint>)
- (rule): Promise<MockedEndpoint>
Parameters
- rule: RequestRuleData
Returns Promise<MockedEndpoint>
Returns RequestRuleBuilder
- addRule: ((rule: RequestRuleData) => Promise<MockedEndpoint>)
- new
Request Rule Builder(method, path, addRule): RequestRuleBuilder Parameters
- method: Method
- path: undefined | string | RegExp
- addRule: ((rule: RequestRuleData) => Promise<MockedEndpoint>)
- (rule): Promise<MockedEndpoint>
Parameters
- rule: RequestRuleData
Returns Promise<MockedEndpoint>
Returns RequestRuleBuilder
as
- as
Priority(priority): this Set the rule priority. Any matching rule with a higher priority will always +take precedence over a matching lower-priority rule, unless the higher rule +has an explicit completion check (like
+.once()) that has already been +completed.The RulePriority enum defines the standard values useful for most cases, +but any positive number may be used for advanced configurations.
+In many cases it may be simpler to use forUnmatchedRequest() to set a fallback +rule explicitly, rather than manually setting the priority here.
+Parameters
- priority: number
Returns this
Responses
then
- then
Callback(callback): Promise<MockedEndpoint> Call the given callback for any matched requests that are received, +and build a response from the result.
+The callback should return a response object with the fields as +defined by CallbackResponseMessageResult to define the response, +or the string 'close' to immediately close the connection. The callback +can be asynchronous, in which case it should return this value wrapped +in a promise.
+If the callback throws an exception, the server will return a 500 +with the exception message.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- callback: ((request: CompletedRequest) => MaybePromise<CallbackResponseResult>)
- (request): MaybePromise<CallbackResponseResult>
Parameters
- request: CompletedRequest
Returns MaybePromise<CallbackResponseResult>
Returns Promise<MockedEndpoint>
- callback: ((request: CompletedRequest) => MaybePromise<CallbackResponseResult>)
then
- then
Close Connection(): Promise<MockedEndpoint> Close connections that match this rule immediately, without +any status code or response.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
then
- then
Forward To(forwardToLocation, options?): Promise<MockedEndpoint> Forward matched requests on to the specified forwardToUrl. The url +specified must not include a path. Otherwise, an error is thrown. +The path portion of the original request url is used instead.
+The url may optionally contain a protocol. If it does, it will override +the protocol (and potentially the port, if unspecified) of the request. +If no protocol is specified, the protocol (and potentially the port) +of the original request URL will be used instead.
+This method takes options to configure how the request is passed +through. See PassThroughHandlerOptions for the full details +of the options available.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- forwardToLocation: string
- options: Omit<PassThroughHandlerOptions, "forwarding"> & {
forwarding?: Omit<undefined | ForwardingOptions, "targetHost">;
} = {}
Returns Promise<MockedEndpoint>
then
- then
From File(status, filePath, headers?): Promise<MockedEndpoint> Reply to matched requests with a given status code and the current contents +of a given file. The status message and headers can also be optionally +provided here. If no headers are provided, only the standard required +headers are set.
+The file is read near-fresh for each request, and external changes to its +content will be immediately appear in all subsequent requests.
+If one string argument is provided, it's used as the body file path. +If two are provided (even if one is empty), then 1st is the status message, +and the 2nd the body. This matches the argument order of thenReply().
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- status: number
- filePath: string
Optionalheaders: Headers
Returns Promise<MockedEndpoint>
- then
From File(status, statusMessage, filePath, headers?): Promise<MockedEndpoint> Parameters
- status: number
- statusMessage: string
- filePath: string
Optionalheaders: Headers
Returns Promise<MockedEndpoint>
then
- then
Json(status, data, headers?): Promise<MockedEndpoint> Reply to matched requests with the given status & JSON and (optionally) +extra headers.
+This method is (approximately) shorthand for: +server.forGet(...).thenReply(status, JSON.stringify(data), { 'Content-Type': 'application/json' })
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- status: number
- data: object
- headers: Headers = {}
Returns Promise<MockedEndpoint>
then
- then
Pass Through(options?): Promise<MockedEndpoint> Pass matched requests through to their real destination. This works +for proxied requests only, direct requests will be rejected with +an error.
+This method takes options to configure how the request is passed +through. See PassThroughHandlerOptions for the full details +of the options available.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
Optionaloptions: PassThroughHandlerOptions
Returns Promise<MockedEndpoint>
then
- then
Reply(status, data?, headers?, trailers?): Promise<MockedEndpoint> Reply to matched requests with a given status code and (optionally) status message, +body, headers & trailers.
+If one string argument is provided, it's used as the body. If two are +provided (even if one is empty) then the 1st is the status message, and +the 2nd the body. If no headers are provided, only the standard required +headers are set, e.g. Date and Transfer-Encoding.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
Returns Promise<MockedEndpoint>
- then
Reply(status, statusMessage, data, headers?, trailers?): Promise<MockedEndpoint> Parameters
Returns Promise<MockedEndpoint>
then
- then
Reset Connection(): Promise<MockedEndpoint> Reset connections that match this rule immediately, sending a TCP +RST packet directly, without any status code or response, and without +cleanly closing the TCP connection.
+This is only supported in Node.js versions (>=16.17, >=18.3.0, or +later), where
+net.Socketincludes theresetAndDestroymethod.Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
then
- then
Send Json Rpc Error(error): Promise<MockedEndpoint> Send a failing error JSON-RPC response to a JSON-RPC request. The error data +can be any JSON-serializable value. If a matching request is received that +is not a valid JSON-RPC request, it will be rejected with an HTTP error.
+Parameters
- error: any
Returns Promise<MockedEndpoint>
then
- then
Send Json Rpc Result(result): Promise<MockedEndpoint> Send a successful JSON-RPC response to a JSON-RPC request. The response data +can be any JSON-serializable value. If a matching request is received that +is not a valid JSON-RPC request, it will be rejected with an HTTP error.
+Parameters
- result: any
Returns Promise<MockedEndpoint>
then
- then
Stream(status, stream, headers?): Promise<MockedEndpoint> Respond immediately with the given status (and optionally, headers), +and then stream the given stream directly as the response body.
+Note that streams can typically only be read once, and as such +this rule will only successfully trigger once. Subsequent requests +will receive a 500 and an explanatory error message. To mock +repeated requests with streams, create multiple streams and mock +them independently.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- status: number
- stream: Readable
Optionalheaders: Headers
Returns Promise<MockedEndpoint>
then
- then
Timeout(): Promise<MockedEndpoint> Hold open connections that match this rule, but never respond +with anything at all, typically causing a timeout on the client side.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
Class ServerMockedEndpoint
A mocked endpoint provides methods to see the current state of +a mock rule.
+Implements
Index
Constructors
constructor
- new
Server Mocked Endpoint(rule): ServerMockedEndpoint Parameters
- rule: WebSocketRule | RequestRule
Returns ServerMockedEndpoint
Methods
[custom]
get
- get
Seen Requests(): Promise<CompletedRequest[]> Get the requests that this endpoint has seen so far.
+This method returns a promise, which resolves with the requests seen +up until now, once all ongoing requests have terminated. The returned +lists are immutable, so won't change if more requests arrive in future. +Call
+getSeenRequestsagain later to get an updated list.Requests are included here once the response is completed, even if the request +itself failed, the responses failed or exceptions are thrown elsewhere. To +watch for errors or detailed response info, look at the various server.on(event) +methods.
+Returns Promise<CompletedRequest[]>
is
- is
Pending(): Promise<boolean> Reports whether this endpoint is still pending: if it either hasn't seen the +specified number of requests (if one was specified e.g. with .twice()) +or if it hasn't seen at least one request, by default.
+This method returns a promise, which resolves with the result once all +ongoing requests have terminated.
+Returns Promise<boolean>
to
Class WebSocketRule
Hierarchy (view full)
- Explainable
- WebSocketRule
Implements
Implemented by
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Web Socket Rule(data): WebSocketRule Parameters
- data: WebSocketRuleData
Returns WebSocketRule
Methods
dispose
explain
handle
- handle(request, response, head, record): Promise<void>
Parameters
- request: OngoingRequest
- response: Socket
- head: Buffer
- record: boolean
Returns Promise<void>
- handle(req, res, head, record): Promise<void>
Parameters
- req: OngoingRequest
- res: Socket
- head: Buffer
- record: boolean
Returns Promise<void>
is
matches
- matches(request): MaybePromise<boolean>
Parameters
- request: OngoingRequest
Returns MaybePromise<boolean>
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class WebSocketRuleBuilder
WebSocketRuleBuilder
+A builder for defining websocket mock rules. Create one using
+.forAnyWebSocket(path) on a Mockttp instance, then call whatever
+methods you'd like here to define more precise matching behaviour,
+control how the connection is handled, and how many times this
+rule should be applied.
When you're done, call a .thenX() method to register the configured rule
+with the server. These return a promise for a MockedEndpoint, which can be
+used to verify the details of the requests matched by the rule.
This returns a promise because rule registration can be asynchronous,
+either when using a remote server or testing in the browser. Wait for the
+promise returned by .thenX() methods to guarantee that the rule has taken
+effect before sending requests to it.
Hierarchy
- BaseRuleBuilder
- WebSocketRuleBuilder
Index
Completion
Matching
Other
Responses
Matching
for
- for
Host(host): this Match only requests sent to the given host, i.e. the full hostname plus +port included in the request.
+This can behave somewhat confusingly when matching against the default +ports for a protocol (i.e. 80/443), or when specifying a hostname here +without specifying the port. In those cases it's usually better to use +forHostname and/or forPort instead to explicit match the content you're +interested in.
+Parameters
- host: string
Returns this
for
for
matching
- matching(content): this
Match only requests when the callback returns true
+Parameters
- content: ((request: CompletedRequest) => MaybePromise<boolean>)
- (request): MaybePromise<boolean>
Parameters
- request: CompletedRequest
Returns MaybePromise<boolean>
Returns this
- content: ((request: CompletedRequest) => MaybePromise<boolean>)
with
with
with
with
with
with
with
with
- with
Json Body Including(json): this Match only requests whose bodies match (contain equivalent +values, ignoring extra values) the given object, when +parsed as JSON. Matching behaviour is the same as Lodash's +_.isMatch method.
+Note that this only tests that the body can be parsed +as JSON - it doesn't require a content-type header.
+Parameters
- json: {}
Returns this
- json: {}
with
- with
Multipart Form(...matchConditions): this Match only requests whose bodies include the given multipart form data.
+This can take any number of form parts to look for. Each part is specified +with MultipartFieldMatchCondition object containing one or more of +
+name(string),filename(string) andcontent(string or buffer) as +fields to match against in the form data.Requests are matched if all conditions match at least one part in the +request's form data.
+Parameters
Rest...matchConditions: MultipartFieldMatchCondition[]
Returns this
with
with
with
Other
constructor
- new
Web Socket Rule Builder(addRule): WebSocketRuleBuilder Mock rule builders should be constructed through the Mockttp instance you're +using, not directly. You shouldn't ever need to call this constructor.
+Parameters
- addRule: ((rule: WebSocketRuleData) => Promise<MockedEndpoint>)
- (rule): Promise<MockedEndpoint>
Parameters
- rule: WebSocketRuleData
Returns Promise<MockedEndpoint>
Returns WebSocketRuleBuilder
- addRule: ((rule: WebSocketRuleData) => Promise<MockedEndpoint>)
as
- as
Priority(priority): this Set the rule priority. Any matching rule with a higher priority will always +take precedence over a matching lower-priority rule, unless the higher rule +has an explicit completion check (like
+.once()) that has already been +completed.The RulePriority enum defines the standard values useful for most cases, +but any positive number may be used for advanced configurations.
+In many cases it may be simpler to use forUnmatchedRequest() to set a fallback +rule explicitly, rather than manually setting the priority here.
+Parameters
- priority: number
Returns this
Responses
then
- then
Close Connection(): Promise<MockedEndpoint> Close connections that match this rule immediately, without accepting +the socket or sending any other response.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
then
- then
Echo(): Promise<MockedEndpoint> Accept incoming WebSocket connections, and echo every message +received on the WebSocket back to the client.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
then
- then
Forward To(forwardToLocation, options?): Promise<MockedEndpoint> Forward matched websockets on to the specified forwardToUrl. The url +specified must not include a path or an error will be thrown. +The path portion of the original request url is used instead.
+The url may optionally contain a protocol. If it does, it will override +the protocol (and potentially the port, if unspecified) of the request. +If no protocol is specified, the protocol (and potentially the port) +of the original request URL will be used instead.
+This method takes options to configure how the request is passed +through. See PassThroughWebSocketHandlerOptions for the full +details of the options available.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- forwardToLocation: string
- options: Omit<PassThroughHandlerConnectionOptions, "forwarding"> & {
forwarding?: Omit<undefined | ForwardingOptions, "targetHost">;
} = {}
Returns Promise<MockedEndpoint>
then
- then
Passively Listen(): Promise<MockedEndpoint> Accept incoming WebSocket connections, and simply listen to +incoming messages without ever sending anything in return.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
then
- then
Pass Through(options?): Promise<MockedEndpoint> Pass matched websockets through to their real destination. This works +for proxied requests only, and direct requests will be rejected with +an error.
+This method takes options to configure how the request is passed +through. See PassThroughWebSocketHandlerOptions for the full +details of the options available.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- options: PassThroughHandlerConnectionOptions = {}
Returns Promise<MockedEndpoint>
then
- then
Reject Connection(statusCode, statusMessage?, headers?, body?): Promise<MockedEndpoint> Rejects connections, sending an HTTP response with the given +status, message and body, to explicitly refuse the WebSocket +handshake.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Parameters
- statusCode: number
OptionalstatusMessage: stringOptionalheaders: HeadersOptionalbody: string | Buffer
Returns Promise<MockedEndpoint>
then
- then
Reset Connection(): Promise<MockedEndpoint> Reset connections that match this rule immediately, sending a TCP +RST packet directly, without accepting the socket or sending any +other response, and without cleanly closing the TCP connection.
+This is only supported in Node.js versions (>=16.17, >=18.3.0, or +later), where
+net.Socketincludes theresetAndDestroymethod.Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
then
- then
Timeout(): Promise<MockedEndpoint> Hold open connections that match this rule, but never respond +with anything at all, typically causing a timeout on the client side.
+Calling this method registers the rule with the server, so it +starts to handle requests.
+This method returns a promise that resolves with a mocked endpoint. +Wait for the promise to confirm that the rule has taken effect +before sending requests to be matched. The mocked endpoint +can be used to assert on the requests matched by this rule.
+Returns Promise<MockedEndpoint>
Class CallbackMatcher
Hierarchy (view full)
- Serializable
- CallbackMatcher
Implements
Constructors
constructor
- new
Callback Matcher(callback): CallbackMatcher Parameters
- callback: ((request: CompletedRequest) => MaybePromise<boolean>)
- (request): MaybePromise<boolean>
Parameters
- request: CompletedRequest
Returns MaybePromise<boolean>
Returns CallbackMatcher
- callback: ((request: CompletedRequest) => MaybePromise<boolean>)
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class CookieMatcher
Hierarchy (view full)
- Serializable
- CookieMatcher
Implements
Constructors
constructor
- new
Cookie Matcher(cookie): CookieMatcher Parameters
- cookie: {
[key: string]: string;
}[key: string]: string
Returns CookieMatcher
- cookie: {
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class ExactQueryMatcher
Hierarchy (view full)
- Serializable
- ExactQueryMatcher
Implements
Constructors
constructor
- new
Exact Query Matcher(query): ExactQueryMatcher Parameters
- query: string
Returns ExactQueryMatcher
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class FormDataMatcher
Hierarchy (view full)
- Serializable
- FormDataMatcher
Implements
Constructors
constructor
- new
Form Data Matcher(formData): FormDataMatcher Parameters
- formData: {
[key: string]: string;
}[key: string]: string
Returns FormDataMatcher
- formData: {
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class HeaderMatcher
Hierarchy (view full)
- Serializable
- HeaderMatcher
Implements
Constructors
constructor
- new
Header Matcher(headersInput): HeaderMatcher Parameters
- headersInput: {
[key: string]: string;
}[key: string]: string
Returns HeaderMatcher
- headersInput: {
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class HostMatcher
Hierarchy (view full)
- Serializable
- HostMatcher
Implements
Constructors
constructor
- new
Host Matcher(host): HostMatcher Parameters
- host: string
Returns HostMatcher
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class HostnameMatcher
Hierarchy (view full)
- Serializable
- HostnameMatcher
Implements
Constructors
constructor
- new
Hostname Matcher(hostname): HostnameMatcher Parameters
- hostname: string
Returns HostnameMatcher
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class JsonBodyFlexibleMatcher
Hierarchy (view full)
- Serializable
- JsonBodyFlexibleMatcher
Implements
Constructors
constructor
- new
Json Body Flexible Matcher(body): JsonBodyFlexibleMatcher Parameters
- body: {}
Returns JsonBodyFlexibleMatcher
- body: {}
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class JsonBodyMatcher
Hierarchy (view full)
- Serializable
- JsonBodyMatcher
Implements
Constructors
constructor
- new
Json Body Matcher(body): JsonBodyMatcher Parameters
- body: {}
Returns JsonBodyMatcher
- body: {}
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class MethodMatcher
Hierarchy (view full)
- Serializable
- MethodMatcher
Implements
Constructors
constructor
- new
Method Matcher(method): MethodMatcher Parameters
- method: Method
Returns MethodMatcher
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class MultipartFormDataMatcher
Hierarchy (view full)
- Serializable
- MultipartFormDataMatcher
Implements
Index
Constructors
constructor
- new
Multipart Form Data Matcher(matchConditions): MultipartFormDataMatcher Parameters
- matchConditions: MultipartFieldMatchCondition[]
Returns MultipartFormDataMatcher
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class PortMatcher
Hierarchy (view full)
- Serializable
- PortMatcher
Implements
Constructors
constructor
- new
Port Matcher(port): PortMatcher Parameters
- port: number
Returns PortMatcher
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class ProtocolMatcher
Hierarchy (view full)
- Serializable
- ProtocolMatcher
Implements
Constructors
constructor
- new
Protocol Matcher(protocol): ProtocolMatcher Parameters
- protocol:
| "http"
| "https"
| "ws"
| "wss"
Returns ProtocolMatcher
- protocol:
Properties
protocol
| "http"
| "https"
| "ws"
| "wss"
Readonlytype
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class QueryMatcher
Hierarchy (view full)
- Serializable
- QueryMatcher
Implements
Index
Constructors
constructor
- new
Query Matcher(queryObjectInput): QueryMatcher Parameters
- queryObjectInput: {
[key: string]: string | number | (string | number)[];
}[key: string]: string | number | (string | number)[]
Returns QueryMatcher
- queryObjectInput: {
Properties
query
[key: string]: string | string[];
}
Readonlytype
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class RawBodyIncludesMatcher
Hierarchy (view full)
- Serializable
- RawBodyIncludesMatcher
Implements
Constructors
constructor
- new
Raw Body Includes Matcher(content): RawBodyIncludesMatcher Parameters
- content: string
Returns RawBodyIncludesMatcher
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class RawBodyMatcher
Hierarchy (view full)
- Serializable
- RawBodyMatcher
Implements
Constructors
constructor
- new
Raw Body Matcher(content): RawBodyMatcher Parameters
- content: string
Returns RawBodyMatcher
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class RegexBodyMatcher
Hierarchy (view full)
- Serializable
- RegexBodyMatcher
Implements
Index
Constructors
constructor
- new
Regex Body Matcher(regex): RegexBodyMatcher Parameters
- regex: RegExp
Returns RegexBodyMatcher
Properties
Readonlyregex
Readonlytype
Methods
dispose
explain
matches
- matches(request): Promise<boolean>
Parameters
- request: OngoingRequest
Returns Promise<boolean>
Class RegexPathMatcher
Hierarchy (view full)
- Serializable
- RegexPathMatcher
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Regex Path Matcher(regex): RegexPathMatcher Parameters
- regex: RegExp
Returns RegexPathMatcher
Properties
Readonlyregex
Readonlyregex
Readonlytype
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class RegexUrlMatcher
Hierarchy (view full)
- Serializable
- RegexUrlMatcher
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Regex Url Matcher(regex): RegexUrlMatcher Parameters
- regex: RegExp
Returns RegexUrlMatcher
Properties
Readonlyregex
Readonlyregex
Readonlytype
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class SimplePathMatcher
Hierarchy (view full)
- Serializable
- SimplePathMatcher
Implements
Constructors
constructor
- new
Simple Path Matcher(path): SimplePathMatcher Parameters
- path: string
Returns SimplePathMatcher
Methods
dispose
explain
matches
- matches(request): boolean
Parameters
- request: OngoingRequest
Returns boolean
Class WildcardMatcher
Hierarchy (view full)
- Serializable
- WildcardMatcher
Implements
Index
Constructors
constructor
- new
Wildcard Matcher(): WildcardMatcher Returns WildcardMatcher
Class CallbackHandlerDefinition
Hierarchy (view full)
- Serializable
- CallbackHandlerDefinition
Implements
Index
Constructors
constructor
- new
Callback Handler Definition(callback): CallbackHandlerDefinition Parameters
- callback: ((request: CompletedRequest) => MaybePromise<CallbackResponseResult>)
- (request): MaybePromise<CallbackResponseResult>
Parameters
- request: CompletedRequest
Returns MaybePromise<CallbackResponseResult>
Returns CallbackHandlerDefinition
- callback: ((request: CompletedRequest) => MaybePromise<CallbackResponseResult>)
Class CloseConnectionHandlerDefinition
Hierarchy (view full)
- Serializable
- CloseConnectionHandlerDefinition
Implements
Index
Constructors
constructor
- new
Close Connection Handler Definition(): CloseConnectionHandlerDefinition Returns CloseConnectionHandlerDefinition
Class FileHandlerDefinition
Hierarchy (view full)
- Serializable
- FileHandlerDefinition
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
File Handler Definition(status, statusMessage, filePath, headers?): FileHandlerDefinition Parameters
- status: number
- statusMessage: undefined | string
- filePath: string
Optionalheaders: Headers
Returns FileHandlerDefinition
Class JsonRpcResponseHandlerDefinition
Hierarchy (view full)
- Serializable
- JsonRpcResponseHandlerDefinition
Implements
Index
Constructors
constructor
- new
Json Rpc Response Handler Definition(result): JsonRpcResponseHandlerDefinition Parameters
- result: {
error?: undefined;
result: any;
} | {
error: any;
result?: undefined;
}
Returns JsonRpcResponseHandlerDefinition
- result: {
Class PassThroughHandlerDefinition
Hierarchy (view full)
- Serializable
- PassThroughHandlerDefinition
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Pass Through Handler Definition(options?): PassThroughHandlerDefinition Parameters
- options: PassThroughHandlerOptions = {}
Returns PassThroughHandlerDefinition
Properties
Optional Readonlybefore
Optional Readonlybefore
Readonlyclient
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
}
ReadonlyextraCACertificates
Optional Readonlyforwarding
Readonlyignore
Optional Readonlylookup
Optional Readonlyproxy
Readonlysimulate
Optional Readonlytransform
Optional Readonlytransform
Readonlytype
Class ResetConnectionHandlerDefinition
Hierarchy (view full)
- Serializable
- ResetConnectionHandlerDefinition
Implements
Index
Constructors
constructor
- new
Reset Connection Handler Definition(): ResetConnectionHandlerDefinition Returns ResetConnectionHandlerDefinition
Class SimpleHandlerDefinition
Hierarchy (view full)
- Serializable
- SimpleHandlerDefinition
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Simple Handler Definition(status, statusMessage?, data?, headers?, trailers?): SimpleHandlerDefinition Parameters
- status: number
OptionalstatusMessage: stringOptionaldata:
| string
| Uint8Array
| Buffer
| SerializedBufferOptionalheaders: HeadersOptionaltrailers: Trailers
Returns SimpleHandlerDefinition
Class StreamHandlerDefinition
Hierarchy (view full)
- Serializable
- StreamHandlerDefinition
Implements
Constructors
constructor
- new
Stream Handler Definition(status, stream, headers?): StreamHandlerDefinition Parameters
- status: number
- stream: Readable & {
done?: true;
} Optionalheaders: Headers
Returns StreamHandlerDefinition
Class TimeoutHandlerDefinition
Hierarchy (view full)
- Serializable
- TimeoutHandlerDefinition
Implements
Index
Constructors
constructor
- new
Timeout Handler Definition(): TimeoutHandlerDefinition Returns TimeoutHandlerDefinition
Class AbortError
Hierarchy
- TypedError
- AbortError
Index
Constructors
Properties
Constructors
constructor
- new
Abort Error(message, code?): AbortError Parameters
- message: string
Optionalcode: string
Returns AbortError
Class CallbackHandler
Hierarchy (view full)
- CallbackHandlerDefinition
- CallbackHandler
Constructors
constructor
- new
Callback Handler(callback): CallbackHandler Parameters
- callback: ((request: CompletedRequest) => MaybePromise<CallbackResponseResult>)
- (request): MaybePromise<CallbackResponseResult>
Parameters
- request: CompletedRequest
Returns MaybePromise<CallbackResponseResult>
Returns CallbackHandler
- callback: ((request: CompletedRequest) => MaybePromise<CallbackResponseResult>)
Methods
dispose
explain
handle
- handle(request, response): Promise<void>
Parameters
- request: OngoingRequest
- response: OngoingResponse
Returns Promise<void>
Class CloseConnectionHandler
Hierarchy (view full)
- CloseConnectionHandlerDefinition
- CloseConnectionHandler
Index
Constructors
constructor
- new
Close Connection Handler(): CloseConnectionHandler Returns CloseConnectionHandler
Methods
dispose
explain
handle
- handle(request): Promise<void>
Parameters
- request: OngoingRequest
Returns Promise<void>
Class FileHandler
Hierarchy (view full)
- FileHandlerDefinition
- FileHandler
Index
Constructors
Properties
Methods
Constructors
constructor
- new
File Handler(status, statusMessage, filePath, headers?): FileHandler Parameters
- status: number
- statusMessage: undefined | string
- filePath: string
Optionalheaders: Headers
Returns FileHandler
Properties
file
Optionalheaders
status
status
Readonlytype
Methods
dispose
explain
handle
- handle(_request, response): Promise<void>
Parameters
- _request: OngoingRequest
- response: OngoingResponse
Returns Promise<void>
Class JsonRpcResponseHandler
Hierarchy (view full)
- JsonRpcResponseHandlerDefinition
- JsonRpcResponseHandler
Constructors
constructor
- new
Json Rpc Response Handler(result): JsonRpcResponseHandler Parameters
- result: {
error?: undefined;
result: any;
} | {
error: any;
result?: undefined;
}
Returns JsonRpcResponseHandler
- result: {
Properties
Readonlyresult
error?: undefined;
result: any;
} | {
error: any;
result?: undefined;
}
Readonlytype
Methods
dispose
explain
handle
- handle(request, response): Promise<void>
Parameters
- request: OngoingRequest
- response: OngoingResponse
Returns Promise<void>
Class PassThroughHandler
Hierarchy (view full)
- PassThroughHandlerDefinition
- PassThroughHandler
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Pass Through Handler(options?): PassThroughHandler Parameters
- options: PassThroughHandlerOptions = {}
Returns PassThroughHandler
Properties
Optional Readonlybefore
Optional Readonlybefore
Readonlyclient
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
}
ReadonlyextraCACertificates
Optional Readonlyforwarding
Readonlyignore
Optional Readonlylookup
Optional Readonlyproxy
Readonlysimulate
Optional Readonlytransform
Optional Readonlytransform
Readonlytype
Methods
dispose
explain
handle
- handle(clientReq, clientRes, options): Promise<void>
Parameters
- clientReq: OngoingRequest
- clientRes: OngoingResponse
- options: RequestHandlerOptions
Returns Promise<void>
Class ResetConnectionHandler
Hierarchy (view full)
- ResetConnectionHandlerDefinition
- ResetConnectionHandler
Index
Constructors
constructor
- new
Reset Connection Handler(): ResetConnectionHandler Returns ResetConnectionHandler
Methods
dispose
explain
handle
- handle(request): Promise<void>
Parameters
- request: OngoingRequest
Returns Promise<void>
Class SimpleHandler
Hierarchy (view full)
- SimpleHandlerDefinition
- SimpleHandler
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Simple Handler(status, statusMessage?, data?, headers?, trailers?): SimpleHandler Parameters
- status: number
OptionalstatusMessage: stringOptionaldata:
| string
| Uint8Array
| Buffer
| SerializedBufferOptionalheaders: HeadersOptionaltrailers: Trailers
Returns SimpleHandler
Properties
Optionaldata
Optionalheaders
status
Optionalstatus
Optionaltrailers
Readonlytype
Methods
dispose
explain
handle
- handle(_request, response): Promise<void>
Parameters
- _request: OngoingRequest
- response: OngoingResponse
Returns Promise<void>
Class StreamHandler
Hierarchy (view full)
- StreamHandlerDefinition
- StreamHandler
Constructors
constructor
- new
Stream Handler(status, stream, headers?): StreamHandler Parameters
- status: number
- stream: Readable & {
done?: true;
} Optionalheaders: Headers
Returns StreamHandler
Properties
Optionalheaders
status
stream
done?: true;
}
Readonlytype
Methods
dispose
explain
handle
- handle(_request, response): Promise<void>
Parameters
- _request: OngoingRequest
- response: OngoingResponse
Returns Promise<void>
Class TimeoutHandler
Hierarchy (view full)
- TimeoutHandlerDefinition
- TimeoutHandler
Index
Constructors
constructor
- new
Timeout Handler(): TimeoutHandler Returns TimeoutHandler
Class EchoWebSocketHandlerDefinition
Hierarchy (view full)
- Serializable
- EchoWebSocketHandlerDefinition
Implements
Index
Constructors
constructor
- new
Echo Web Socket Handler Definition(): EchoWebSocketHandlerDefinition Returns EchoWebSocketHandlerDefinition
Class ListenWebSocketHandlerDefinition
Hierarchy (view full)
- Serializable
- ListenWebSocketHandlerDefinition
Implements
Index
Constructors
constructor
- new
Listen Web Socket Handler Definition(): ListenWebSocketHandlerDefinition Returns ListenWebSocketHandlerDefinition
Class PassThroughWebSocketHandlerDefinition
Hierarchy (view full)
- Serializable
- PassThroughWebSocketHandlerDefinition
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Pass Through Web Socket Handler Definition(options?): PassThroughWebSocketHandlerDefinition Parameters
- options: PassThroughHandlerConnectionOptions = {}
Returns PassThroughWebSocketHandlerDefinition
Properties
Readonlyclient
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
}
ReadonlyextraCACertificates
Optional Readonlyforwarding
Readonlyignore
Readonlylookup
Optional Readonlyproxy
Readonlytype
Class RejectWebSocketHandlerDefinition
Hierarchy (view full)
- Serializable
- RejectWebSocketHandlerDefinition
Implements
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Reject Web Socket Handler Definition(statusCode, statusMessage?, headers?, body?): RejectWebSocketHandlerDefinition Parameters
- statusCode: number
- statusMessage: string = 'WebSocket rejected'
- headers: Headers = {}
- body: string | Buffer = ''
Returns RejectWebSocketHandlerDefinition
Class EchoWebSocketHandler
Hierarchy (view full)
- EchoWebSocketHandlerDefinition
- EchoWebSocketHandler
Index
Constructors
constructor
- new
Echo Web Socket Handler(): EchoWebSocketHandler Returns EchoWebSocketHandler
Methods
dispose
explain
handle
- handle(req, socket, head): Promise<void>
Parameters
- req: OngoingRequest & IncomingMessage
- socket: Socket
- head: Buffer
Returns Promise<void>
Class ListenWebSocketHandler
Hierarchy (view full)
- ListenWebSocketHandlerDefinition
- ListenWebSocketHandler
Index
Constructors
constructor
- new
Listen Web Socket Handler(): ListenWebSocketHandler Returns ListenWebSocketHandler
Methods
dispose
explain
handle
- handle(req, socket, head): Promise<void>
Parameters
- req: OngoingRequest & IncomingMessage
- socket: Socket
- head: Buffer
Returns Promise<void>
Class PassThroughWebSocketHandler
Hierarchy (view full)
- PassThroughWebSocketHandlerDefinition
- PassThroughWebSocketHandler
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Pass Through Web Socket Handler(options?): PassThroughWebSocketHandler Parameters
- options: PassThroughHandlerConnectionOptions = {}
Returns PassThroughWebSocketHandler
Properties
Readonlyclient
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
}
ReadonlyextraCACertificates
Optional Readonlyforwarding
Readonlyignore
Readonlylookup
Optional Readonlyproxy
Readonlytype
Methods
dispose
explain
handle
- handle(req, socket, head): Promise<void>
Parameters
- req: OngoingRequest
- socket: Socket
- head: Buffer
Returns Promise<void>
Class RejectWebSocketHandler
Hierarchy (view full)
- RejectWebSocketHandlerDefinition
- RejectWebSocketHandler
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Reject Web Socket Handler(statusCode, statusMessage?, headers?, body?): RejectWebSocketHandler Parameters
- statusCode: number
- statusMessage: string = 'WebSocket rejected'
- headers: Headers = {}
- body: string | Buffer = ''
Returns RejectWebSocketHandler
Properties
Readonlybody
Readonlyheaders
Readonlystatus
Readonlystatus
Readonlytype
Methods
dispose
explain
handle
- handle(req, socket, head): Promise<void>
Parameters
- req: OngoingRequest
- socket: Socket
- head: Buffer
Returns Promise<void>
Function deserialize
- deserialize<T, C>(data, stream, ruleParams, lookup): InstanceType<C>
Type Parameters
- T extends SerializedValue<Serializable>
- C extends {
deserialize(data: any, channel: ClientServerChannel, ruleParams: RuleParameters): any;
new (...args: any): any;
}
Parameters
- data: T
- stream: Duplex
- ruleParams: RuleParameters
- lookup: {
[key: string]: C;
}[key: string]: C
Returns InstanceType<C>
Function deserializeProxyConfig
- deserialize
Proxy Config(proxyConfig, channel, ruleParams): ProxySettingSource Parameters
- proxyConfig: SerializedProxyConfig
- channel: ClientServerChannel
- ruleParams: RuleParameters
Returns ProxySettingSource
Function ensureParamsDeferenced
- ensure
Params Deferenced<T>(value, ruleParams): T Type Parameters
Parameters
- value: T | SerializedRuleParameterReference<T>
- ruleParams: RuleParameters
Returns T
Function serialize
- serialize<T>(obj, stream): SerializedValue<T>
Type Parameters
- T extends Serializable
Parameters
- obj: T
- stream: Duplex
Returns SerializedValue<T>
Function serializeProxyConfig
- serialize
Proxy Config(proxyConfig, channel): SerializedProxyConfig Parameters
- proxyConfig: ProxyConfig
- channel: ClientServerChannel
Returns SerializedProxyConfig
Function generateCACertificate
- generateCACertificate(options?): Promise<{
cert: string;
key: string;
}> Generate a CA certificate for mocking HTTPS.
+Returns a promise, for an object with key and cert properties, +containing the generated private key and certificate in PEM format.
+These can be saved to disk, and their paths passed +as HTTPS options to a Mockttp server.
+Parameters
- options: {
bits?: number;
commonName?: string;
countryName?: string;
nameConstraints?: {
permitted?: string[];
};
organizationName?: string;
} = {}Optionalbits?: numberOptionalcommonName?: string OptionalcountryName?: string OptionalnameConstraints?: {
permitted?: string[];
}Optionalpermitted?: string[]
OptionalorganizationName?: string
Returns Promise<{
cert: string;
key: string;
}>- options: {
Function generateSPKIFingerprint
- generateSPKIFingerprint(certPem): string
Parameters
- certPem: PEM
Returns string
Function getAdminServer
- get
Admin Server(options?): MockttpAdminServer Get a Mockttp admin server, which can be used with a Mockttp remote client to create +& manage Mockttp instances either from remote machines or from local environments +that lack necessary capabilities, e.g. to use Mockttp from inside a browser.
+This function exists so you can set up these servers programmatically, but for most +usage you can just run your tests via the
+mockttpbinary, which will automatically +start and stop an admin server for you:
+ +mockttp -c <your test command> +Parameters
- options: MockttpAdminServerOptions = {}
Returns MockttpAdminServer
Function getLocal
- get
Local(options?): Mockttp Get a Mockttp instance on the local machine.
+In most simple environments, you can call this method directly and immediately +get a Mockttp instance and start mocking servers.
+In node, the mocked servers will run in process and require no further setup.
+In browsers this is an alias for getRemote. You'll need to start a Mockttp admin server +outside your tests before calling this, which will create and manage your fake servers +outside the browser.
+Parameters
- options: MockttpOptions = {}
Returns Mockttp
Function getRemote
- get
Remote(options?): Mockttp Get a Mockttp instance, controlled through a Mockttp admin server.
+This connects to a Mockttp admin server, and uses that to start +and stop mock servers.
+Parameters
- options: MockttpClientOptions = {}
Returns Mockttp
Function explainMatchers
- explain
Matchers(matchers): string Parameters
- matchers: RequestMatcher[]
Returns string
Function matchesAll
- matches
All(req, matchers): Promise<boolean> Parameters
- req: OngoingRequest
- matchers: RequestMatcher[]
Returns Promise<boolean>
Function resetAdminServer
- reset
Admin Server(options?): Promise<void> Reset a remote admin server, shutting down all Mockttp servers controlled by that +admin server. This is equivalent to calling
+client.stop()for all remote +clients of the target server.This can be useful in some rare cases, where a client might fail to reliably tear down +its own server, e.g. in Cypress testing. In this case, it's useful to reset the +admin server completely remotely without needing access to any previous client +instances, to ensure all servers from previous test runs have been shut down.
+After this is called, behaviour of any previously connected clients is undefined, and +it's likely that they may throw errors or experience other undefined behaviour. Ensure +that
+client.stop()has been called on all active clients before calling this method.Parameters
- options: AdminClientOptions = {}
Returns Promise<void>
mockttp
Class Hierarchy
- Explainable
- RequestMatcher
- CallbackMatcher
- CookieMatcher
- ExactQueryMatcher
- FormDataMatcher
- HeaderMatcher
- HostMatcher
- HostnameMatcher
- JsonBodyFlexibleMatcher
- JsonBodyMatcher
- MethodMatcher
- MultipartFormDataMatcher
- PortMatcher
- ProtocolMatcher
- QueryMatcher
- RawBodyIncludesMatcher
- RawBodyMatcher
- RegexBodyMatcher
- RegexPathMatcher
- RegexUrlMatcher
- SimplePathMatcher
- WildcardMatcher
- CallbackMatcher
- RequestHandlerDefinition
- WebSocketHandlerDefinition
- RequestRule
- WebSocketRule
- RequestMatcher
- Serializable
- RequestMatcher
- CallbackMatcher
- CookieMatcher
- ExactQueryMatcher
- FormDataMatcher
- HeaderMatcher
- HostMatcher
- HostnameMatcher
- JsonBodyFlexibleMatcher
- JsonBodyMatcher
- MethodMatcher
- MultipartFormDataMatcher
- PortMatcher
- ProtocolMatcher
- QueryMatcher
- RawBodyIncludesMatcher
- RawBodyMatcher
- RegexBodyMatcher
- RegexPathMatcher
- RegexUrlMatcher
- SimplePathMatcher
- WildcardMatcher
- CallbackMatcher
- RequestHandlerDefinition
- WebSocketHandlerDefinition
- RuleCompletionChecker
- RequestMatcher
mockttp
Mockttp 
++Part of HTTP Toolkit: powerful tools for building, testing & debugging HTTP(S)
+
These are the API reference docs for Mockttp. If you're not sure what Mockttp is, it's best to start from the README instead.
+On the other hand, if you're looking for detailed documentation, you're in the right place!
+From here you can explore all the exported types and statically exported functions from the sidebar on the right, you can use the search button (top right) to jump to specific documentation by name, or you're not sure you probably want to start at the Mockttp type and follow the types from there.
+Can't find what you're looking for, missing important info, or generally confused? Please file an issue and help Mockttp's docs get better.
+Interface AbortedRequest
error?: {
code?: string;
message?: string;
name?: string;
stack?: string;
};
headers: Headers;
hostname?: string;
httpVersion?: string;
id: string;
matchedRuleId?: string;
method: string;
path: string;
protocol: string;
rawHeaders: RawHeaders;
remoteIpAddress?: string;
remotePort?: number;
tags: string[];
timingEvents: TimingEvents;
url: string;
}
Hierarchy (view full)
- InitiatedRequest
- AbortedRequest
Index
Properties
Properties
Optionalerror
code?: string;
message?: string;
name?: string;
stack?: string;
}
headers
Optionalhostname
Optionalhttp
id
Optionalmatched
method
path
protocol
raw
Optionalremote
Optionalremote
tags
timing
url
Interface ClientError
A client error event describes a request (or our best guess at parsing it), +that wasn't correctly completed, and the error response it received, or +'aborted' if the connection was disconnected before we could respond.
+errorCode?: string;
request: {
headers: Headers;
httpVersion?: string;
id: string;
method?: string;
path?: string;
protocol?: string;
rawHeaders: RawHeaders;
remoteIpAddress?: string;
remotePort?: number;
tags: string[];
timingEvents: TimingEvents;
url?: string;
};
response: "aborted" | CompletedResponse;
}
Index
Properties
Properties
Optionalerror
request
headers: Headers;
httpVersion?: string;
id: string;
method?: string;
path?: string;
protocol?: string;
rawHeaders: RawHeaders;
remoteIpAddress?: string;
remotePort?: number;
tags: string[];
timingEvents: TimingEvents;
url?: string;
}
response
Interface CompletedBody
buffer: Buffer;
getDecodedBuffer(): Promise<undefined | Buffer>;
getFormData(): Promise<undefined | {
[key: string]: string | string[] | undefined;
}>;
getJson(): Promise<undefined | object>;
getMultipartFormData(): Promise<undefined | {
data: Buffer;
filename?: string;
name?: string;
type?: string;
}[]>;
getText(): Promise<undefined | string>;
getUrlEncodedFormData(): Promise<undefined | {
[key: string]: string | string[] | undefined;
}>;
}
Index
Properties
Methods
Properties
buffer
The raw bytes of the response. If a content encoding was used, this is +the raw encoded data.
+ Methods
get
get
- get
Form Data(): Promise<undefined | {
[key: string]: string | string[] | undefined;
}> The contents of the response, decoded, and then parsed automatically as +either one of the form encoding types (either URL-encoded or multipart), +determined automatically from the message content-type header.
+This method is convenient and offers a single mechanism to parse both +formats, but you may want to consider parsing on format explicitly with +the
+getUrlEncodedFormData()orgetMultipartFormData()methods instead.After parsing & decoding, the result is returned asynchronously as a +Promise for a key-value(s) object.
+Returns Promise<undefined | {
[key: string]: string | string[] | undefined;
}>
get
get
- get
Multipart Form Data(): Promise<undefined | {
data: Buffer;
filename?: string;
name?: string;
type?: string;
}[]> The contents of the response, decoded, and then parsed as multi-part +form data. The response is result is returned asynchronously as a +Promise for an array of parts with their names, data and metadata.
+Returns Promise<undefined | {
data: Buffer;
filename?: string;
name?: string;
type?: string;
}[]>
get
get
- get
Url Encoded Form Data(): Promise<undefined | {
[key: string]: string | string[] | undefined;
}> The contents of the response, decoded, parsed as UTF-8 string, and then +parsed as URL-encoded form data. After parsing & decoding, the result is +returned asynchronously as a Promise for a key-value(s) object.
+Returns Promise<undefined | {
[key: string]: string | string[] | undefined;
}>
Interface CompletedRequest
body: CompletedBody;
headers: Headers;
hostname?: string;
httpVersion?: string;
id: string;
matchedRuleId?: string;
method: string;
path: string;
protocol: string;
rawHeaders: RawHeaders;
rawTrailers: RawHeaders;
remoteIpAddress?: string;
remotePort?: number;
tags: string[];
timingEvents: TimingEvents;
trailers: Trailers;
url: string;
}
Hierarchy (view full)
- Request
- CompletedRequest
Index
Properties
Properties
body
headers
Optionalhostname
Optionalhttp
id
Optionalmatched
method
path
protocol
raw
raw
Optionalremote
Optionalremote
tags
timing
trailers
url
Interface CompletedResponse
body: CompletedBody;
headers: Headers;
id: string;
rawHeaders: RawHeaders;
rawTrailers: RawHeaders;
statusCode: number;
statusMessage: string;
tags: string[];
timingEvents: TimingEvents;
trailers: Trailers;
}
Index
Properties
Interface Headers
:authority?: string;
:method?: string;
:path?: string;
:scheme?: string;
content-length?: string;
content-type?: string;
cookie?: string;
host?: string;
user-agent?: string;
[key: string]: undefined | string | string[];
}
Indexable
- [key: string]: undefined | string | string[]
Index
Properties
Properties
Optional:authority
Optional:method
Optional:path
Optional:scheme
Optionalcontent-
Optionalcontent-
Optionalcookie
Optionalhost
Optionaluser-
Interface HttpsOptions
cert: string;
countryName?: string;
key: string;
keyLength?: number;
localityName?: string;
organizationName?: string;
}
Hierarchy
- BaseCAOptions
- HttpsOptions
Index
Properties
Properties
cert
Optionalcountry
The countryName that will be used in the certificate for incoming TLS +connections.
+key
Optionalkey
Minimum key length when generating certificates. Defaults to 2048.
+Optionallocality
The localityName that will be used in the certificate for incoming TLS +connections.
+Optionalorganization
The organizationName that will be used in the certificate for incoming TLS +connections.
+Interface HttpsPathOptions
certPath: string;
countryName?: string;
keyLength?: number;
keyPath: string;
localityName?: string;
organizationName?: string;
}
Hierarchy
- BaseCAOptions
- HttpsPathOptions
Index
Properties
Properties
cert
Optionalcountry
The countryName that will be used in the certificate for incoming TLS +connections.
+Optionalkey
Minimum key length when generating certificates. Defaults to 2048.
+key
Optionallocality
The localityName that will be used in the certificate for incoming TLS +connections.
+Optionalorganization
The organizationName that will be used in the certificate for incoming TLS +connections.
+Interface MockedEndpoint
A mocked endpoint provides methods to see the current state of +a mock rule.
+id: string;
getSeenRequests(): Promise<CompletedRequest[]>;
isPending(): Promise<boolean>;
}
Implemented by
Index
Properties
Methods
Methods
get
- get
Seen Requests(): Promise<CompletedRequest[]> Get the requests that this endpoint has seen so far.
+This method returns a promise, which resolves with the requests seen +up until now, once all ongoing requests have terminated. The returned +lists are immutable, so won't change if more requests arrive in future. +Call
+getSeenRequestsagain later to get an updated list.Requests are included here once the response is completed, even if the request +itself failed, the responses failed or exceptions are thrown elsewhere. To +watch for errors or detailed response info, look at the various server.on(event) +methods.
+Returns Promise<CompletedRequest[]>
is
- is
Pending(): Promise<boolean> Reports whether this endpoint is still pending: if it either hasn't seen the +specified number of requests (if one was specified e.g. with .twice()) +or if it hasn't seen at least one request, by default.
+This method returns a promise, which resolves with the result once all +ongoing requests have terminated.
+Returns Promise<boolean>
Interface MockedEndpointData
explanation?: string;
id: string;
isPending: boolean;
seenRequests: CompletedRequest[];
}
Index
Properties
Interface Mockttp
A mockttp instance allow you to start and stop mock servers and control their behaviour.
+This should be created using the exported getLocal or getRemote methods, like +so:
+const mockServer = require('mockttp').getLocal()
+Call .start() to set up a server on a random port, use .forX methods like .forGet(url),
+.forPost(url) and .forAnyRequest() to get a RequestRuleBuilder and start defining
+mock rules. You can also mock WebSocket requests using .forAnyWebSocket(). Call .stop()
+when your test is complete. An example:
await mockServer.start();
await mockServer.forGet('/abc').thenReply(200, "a response");
// ...Make some requests
await mockServer.stop();
+port: number;
proxyEnv: ProxyEnvConfig;
url: string;
addRequestRule(ruleData: RequestRuleData): Promise<MockedEndpoint>;
addRequestRules(...ruleData: RequestRuleData[]): Promise<MockedEndpoint[]>;
addWebSocketRule(ruleData: WebSocketRuleData): Promise<MockedEndpoint>;
addWebSocketRules(...ruleData: WebSocketRuleData[]): Promise<MockedEndpoint[]>;
enableDebug(): void;
forAnyRequest(): RequestRuleBuilder;
forAnyWebSocket(): 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;
forUnmatchedRequest(): RequestRuleBuilder;
getMockedEndpoints(): Promise<MockedEndpoint[]>;
getPendingEndpoints(): Promise<MockedEndpoint[]>;
getRuleParameterKeys(): Promise<string[]>;
on(event: "request-initiated", callback: ((req: Request) => void)): Promise<void>;
on(event: "request", callback: ((req: CompletedRequest) => void)): Promise<void>;
on(event: "response", callback: ((req: CompletedResponse) => 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: ((req: WebSocketClose) => void)): Promise<void>;
on(event: "abort", callback: ((req: AbortedRequest) => 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: TlsRequest) => void)): Promise<void>;
on(event: "client-error", callback: ((error: ClientError) => void)): Promise<void>;
on<T>(event: "rule-event", callback: ((event: RuleEvent<T>) => void)): Promise<void>;
reset(): void;
setRequestRules(...ruleData: RequestRuleData[]): Promise<MockedEndpoint[]>;
setWebSocketRules(...ruleData: WebSocketRuleData[]): Promise<MockedEndpoint[]>;
start(port?: number | PortRange): Promise<void>;
stop(): Promise<void>;
urlFor(path: string): string;
}
Implemented by
Index
Events
on
- on(event, callback): Promise<void>
Subscribe to hear about request details as soon as the initial request details +(method, path & headers) are received, 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>
- on(event, callback): 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
- event: "request"
- callback: ((req: CompletedRequest) => void)
- (req): void
Parameters
- req: CompletedRequest
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "response"
- callback: ((req: CompletedResponse) => void)
- (req): void
Parameters
- req: CompletedResponse
Returns void
Returns Promise<void>
- on(event, callback): 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: "websocket-request"
- callback: ((req: CompletedRequest) => void)
- (req): void
Parameters
- req: CompletedRequest
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-accepted"
- callback: ((req: CompletedResponse) => void)
- (req): void
Parameters
- req: CompletedResponse
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-message-received"
- callback: ((req: WebSocketMessage) => void)
- (req): void
Parameters
- req: WebSocketMessage
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-message-sent"
- callback: ((req: WebSocketMessage) => void)
- (req): void
Parameters
- req: WebSocketMessage
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "websocket-close"
- callback: ((req: WebSocketClose) => void)
- (req): void
Parameters
- req: WebSocketClose
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "abort"
- callback: ((req: AbortedRequest) => void)
- (req): void
Parameters
- req: AbortedRequest
Returns void
Returns Promise<void>
- on(event, callback): Promise<void>
Subscribe to hear about TLS connections that are passed through the proxy without +interception, due to the
+tlsPassthroughHTTPS 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
- event: "tls-passthrough-opened"
- callback: ((req: TlsPassthroughEvent) => void)
- (req): void
Parameters
- req: TlsPassthroughEvent
Returns void
Returns Promise<void>
- on(event, callback): Promise<void>
Subscribe to hear about closure of TLS connections that were passed through the +proxy without interception, due to the
+tlsPassthroughHTTPS 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
- event: "tls-passthrough-closed"
- callback: ((req: TlsPassthroughEvent) => void)
- (req): void
Parameters
- req: TlsPassthroughEvent
Returns void
Returns Promise<void>
- on(event, callback): 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
- event: "tls-client-error"
- callback: ((req: TlsRequest) => void)
- (req): void
Parameters
- req: TlsRequest
Returns void
Returns Promise<void>
- on(event, callback): 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)
- (error): void
Parameters
- error: ClientError
Returns void
Returns Promise<void>
- on<T>(event, callback): 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
Parameters
Returns Promise<void>
Manual rule definition
add
- add
Request Rule(ruleData): Promise<MockedEndpoint> Adds the given HTTP request rule to the server.
+This is a convenient alias for calling
+addRequestRuleswith one rule, +and extracting the first endpoint result.This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
- ruleData: RequestRuleData
Returns Promise<MockedEndpoint>
add
- add
Request Rules(...ruleData): Promise<MockedEndpoint[]> Adds the given HTTP request rules to the server.
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: RequestRuleData[]
Returns Promise<MockedEndpoint[]>
add
- add
Web Socket Rule(ruleData): Promise<MockedEndpoint> Adds the given websocket rule to the server.
+This is a convenient alias for calling
+addWebSocketRuleswith one rule, +and extracting the first endpoint result.This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
- ruleData: WebSocketRuleData
Returns Promise<MockedEndpoint>
add
- add
Web Socket Rules(...ruleData): Promise<MockedEndpoint[]> Adds the given websocket rules to the server.
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: WebSocketRuleData[]
Returns Promise<MockedEndpoint[]>
set
- set
Request Rules(...ruleData): Promise<MockedEndpoint[]> Set the given HTTP request rules as the only request rules on the server, +replacing any existing rules (except websocket rules).
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: RequestRuleData[]
Returns Promise<MockedEndpoint[]>
set
- set
Web Socket Rules(...ruleData): Promise<MockedEndpoint[]> Set the given websocket rules as the only websocket rules on the server, +replacing all existing websocket rules (but leaving normal rules untouched).
+This API is only useful if you're manually building rules, rather than +using RequestRuleBuilder, and is only for special cases. This approach may +be necessary if you need to configure all your rules in one place to +enable them elsewhere/later.
+Parameters
Rest...ruleData: WebSocketRuleData[]
Returns Promise<MockedEndpoint[]>
Metadata
port
The port the server is running on.
+This will throw an error if read before the server is started.
+proxy
The environment variables typically needed to use this server as a proxy, in a format you +can add to your environment straight away.
+This will throw an error if read before the server is started.
+process.env = Object.assign(process.env, mockServer.proxyEnv)
+url
The root URL of the server.
+This will throw an error if read before the server is started.
+get
- get
Mocked Endpoints(): Promise<MockedEndpoint[]> Returns the set of currently registered mock endpoints.
+Returns Promise<MockedEndpoint[]>
get
- get
Pending Endpoints(): Promise<MockedEndpoint[]> 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<MockedEndpoint[]>
get
- get
Rule Parameter Keys(): Promise<string[]> 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<string[]>
url
Mock HTTP requests
for
- for
Any Request(): RequestRuleBuilder Get a builder for a mock rule that will match any requests on any path.
+This only matches traditional HTTP requests, not websockets, which are handled +separately. To match websockets, use
+.forAnyWebSocket().Returns RequestRuleBuilder
for
- for
Delete(url?): RequestRuleBuilder Get a builder for a mock rule that will match DELETE requests for the given path. +If no path is specified, this matches all DELETE requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Get(url?): RequestRuleBuilder Get a builder for a mock rule that will match GET requests for the given path. +If no path is specified, this matches all GET requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Head(url?): RequestRuleBuilder Get a builder for a mock rule that will match HEAD requests for the given path. +If no path is specified, this matches all HEAD requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Json Rpc Request(match?): RequestRuleBuilder Match JSON-RPC requests, optionally matching a given method and/or params.
+If no method or params are specified, this will match all JSON-RPC requests.
+Params are matched flexibly, using the same logic as .withJsonBodyIncluding(), +so only the included fields are checked and other extra fields are ignored
+Parameters
Optionalmatch: {
method?: string;
params?: any;
}Optionalmethod?: stringOptionalparams?: any
Returns RequestRuleBuilder
for
- for
Options(url?): RequestRuleBuilder Get a builder for a mock rule that will match OPTIONS requests for the given path.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
This can only be used if the
+corsoption has been set to false.If cors is true (the default when using a remote client, e.g. in the browser), +then the mock server automatically handles OPTIONS requests to ensure requests +to the server are allowed by clients observing CORS rules.
+You can pass
+{cors: false}togetLocal/getRemoteto disable this behaviour, +but if you're testing in a browser you will need to ensure you mock all OPTIONS +requests appropriately so that the browser allows your other requests to be sent.Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Patch(url?): RequestRuleBuilder Get a builder for a mock rule that will match PATCH requests for the given path. +If no path is specified, this matches all PATCH requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Post(url?): RequestRuleBuilder Get a builder for a mock rule that will match POST requests for the given path. +If no path is specified, this matches all POST requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Put(url?): RequestRuleBuilder Get a builder for a mock rule that will match PUT requests for the given path. +If no path is specified, this matches all PUT requests.
+The path can be either a string, or a regular expression to match against. +Path matching always ignores query parameters. To match query parameters, +use .withQuery({ a: 'b' }) or withExactQuery('?a=b').
+There are a few supported matching formats:
+-
+
- Relative string paths (
/abc) will be compared only to the request's path, +independent of the host & protocol, ignoring query params.
+ - Absolute string paths with no protocol (
localhost:8000/abc) will be +compared to the URL independent of the protocol, ignoring query params.
+ - Fully absolute string paths (
http://localhost:8000/abc) will be compared +to entire URL, ignoring query params.
+ - Regular expressions can match the absolute URL:
/^http://localhost:8000/abc$/
+ - Regular expressions can also match the path:
/^/abc/
+
Parameters
Optionalurl: string | RegExp
Returns RequestRuleBuilder
- Relative string paths (
for
- for
Unmatched Request(): RequestRuleBuilder Get a builder for a fallback mock rule that will match any unmatched requests +on any path.
+Fallback rules act like any other rule, but they only match if there is no +existing normal rule that matches the request, or if all existing rules have +an explicit execution limit (like
+once()) that has been completed.Returns RequestRuleBuilder
Mock websockets
for
- for
Any Web Socket(): WebSocketRuleBuilder Get a builder for a mock rule that will match all websocket connections.
+Returns WebSocketRuleBuilder
Setup
enable
reset
start
- start(port?): Promise<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.urland.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
Optionalport: number | PortRange
Returns Promise<void>
stop
Interface MockttpAdminServerOptions
corsOptions?: CorsOptions & {
allowPrivateNetworkAccess?: boolean;
strict?: boolean;
};
debug?: boolean;
ruleParameters?: {
[key: string]: any;
};
serverDefaults?: MockttpOptions;
webSocketKeepAlive?: number;
}
Hierarchy
- Omit<AdminServerOptions<{}>, "adminPlugins" | "pluginDefaults">
- MockttpAdminServerOptions
Index
Properties
Properties
Optionalcors
allowPrivateNetworkAccess?: boolean;
strict?: boolean;
}
Set CORS options to limit the sites which can send requests to manage this admin server.
+Optionaldebug
Should the admin server print extra debug information? This enables admin server debugging +only - individual mock session debugging must be enabled separately.
+Optionalrule
[key: string]: any;
}
Some rule options can't easily be specified in remote clients, since they need to access
+server-side state or Node APIs directly. To handle this, referenceable parameters can
+be provided here, and referenced with a { [MOCKTTP_PARAM_REF]: <value> } value in place
+of the real parameter in the remote client.
Optionalserver
Override the default parameters for servers started from this admin server. These values will be +used for each setting that is not explicitly specified by the client when creating a mock server.
+Optionalweb
Set a keep alive frequency in milliseconds for the subscription & stream websockets of each +session, to ensure they remain connected in long-lived connections, especially in browsers which +often close quiet background connections automatically.
+Interface MockttpClientOptions
adminServerUrl?: string;
client?: {
headers?: {
[key: string]: string;
};
};
cors?: boolean | CorsOptions;
debug?: boolean;
http2?: boolean | "fallback";
https?: MockttpHttpsOptions;
maxBodySize?: number;
recordTraffic?: boolean;
suggestChanges?: boolean;
}
Hierarchy (view full)
- MockttpOptions
- MockttpClientOptions
Index
Properties
Properties
Optionaladmin
The full URL to use to connect to a Mockttp admin server when using a +remote (or local but browser) client.
+When using a local server, this option is ignored.
+Optionalclient
headers?: {
[key: string]: string;
};
}
Options to include on all client requests, e.g. to add extra +headers for authentication.
+Optionalcors
Should the server automatically respond to OPTIONS requests with a permissive +response?
+Defaults to true for remote clients (e.g. in the browser), and false otherwise. +If this is set to false, browser requests will typically fail unless you +stub OPTIONS responses by hand.
+Optionaldebug
Should the server print extra debug information?
+Optionalhttp2
Should HTTP/2 be enabled? Can be true, false, or 'fallback'. If true, +HTTP/2 is used for all clients supporting it. If false, HTTP/2 is never +used. If 'fallback' HTTP/2 is used only for clients that do not advertise +support for HTTP/1.1, but HTTP/1.1 is used by preference in all other +cases.
+Client HTTP/2 support is only advertised as part of the TLS options. +When no HTTPS configuration is provided, 'fallback' is equivalent to +false.
+Optionalhttps
The HTTPS settings to be used. Optional, only HTTP interception will be +enabled if omitted. This should be set to either a { key, cert } object +containing the private key and certificate in PEM format, or a { keyPath, +certPath } object containing the path to files containing that content.
+Optionalmax
The maximum body size to process, in bytes.
+Bodies larger than this will be dropped, becoming empty, so they won't match +body matchers, won't be available in .seenRequests, and won't be included in +subscribed event data. Body data will still typically be included in passed +through request & response data, in most cases, so this won't affect the +external HTTP clients otherwise.
+Optionalrecord
Record the requests & response for all traffic matched by each rule, and make +it available via endpoint.getSeenRequests().
+Defaults to true. It can be useful to set this to false if lots of data will +be sent to/via the server, to avoid storing all traffic in memory unnecessarily, +if getSeenRequests will not be used.
+If this is set to false then getSeenRequests() will always return +an empty array. This only disables the built-in persistence of request data, +so traffic can still be captured live or stored elsewhere using +.on('request') & .on('response').
+Optionalsuggest
By default, requests that match no rules will receive an explanation of the +request & existing rules, followed by some suggested example Mockttp code +which could be used to match the rule.
+In some cases where the end client is unaware of Mockttp, these example
+suggestions are just confusing. Set suggestChanges to false to disable it.
Interface MockttpOptions
cors?: boolean | CorsOptions;
debug?: boolean;
http2?: boolean | "fallback";
https?: MockttpHttpsOptions;
maxBodySize?: number;
recordTraffic?: boolean;
suggestChanges?: boolean;
}
Hierarchy (view full)
- MockttpOptions
Index
Properties
Properties
Optionalcors
Should the server automatically respond to OPTIONS requests with a permissive +response?
+Defaults to true for remote clients (e.g. in the browser), and false otherwise. +If this is set to false, browser requests will typically fail unless you +stub OPTIONS responses by hand.
+Optionaldebug
Should the server print extra debug information?
+Optionalhttp2
Should HTTP/2 be enabled? Can be true, false, or 'fallback'. If true, +HTTP/2 is used for all clients supporting it. If false, HTTP/2 is never +used. If 'fallback' HTTP/2 is used only for clients that do not advertise +support for HTTP/1.1, but HTTP/1.1 is used by preference in all other +cases.
+Client HTTP/2 support is only advertised as part of the TLS options. +When no HTTPS configuration is provided, 'fallback' is equivalent to +false.
+Optionalhttps
The HTTPS settings to be used. Optional, only HTTP interception will be +enabled if omitted. This should be set to either a { key, cert } object +containing the private key and certificate in PEM format, or a { keyPath, +certPath } object containing the path to files containing that content.
+Optionalmax
The maximum body size to process, in bytes.
+Bodies larger than this will be dropped, becoming empty, so they won't match +body matchers, won't be available in .seenRequests, and won't be included in +subscribed event data. Body data will still typically be included in passed +through request & response data, in most cases, so this won't affect the +external HTTP clients otherwise.
+Optionalrecord
Record the requests & response for all traffic matched by each rule, and make +it available via endpoint.getSeenRequests().
+Defaults to true. It can be useful to set this to false if lots of data will +be sent to/via the server, to avoid storing all traffic in memory unnecessarily, +if getSeenRequests will not be used.
+If this is set to false then getSeenRequests() will always return +an empty array. This only disables the built-in persistence of request data, +so traffic can still be captured live or stored elsewhere using +.on('request') & .on('response').
+Optionalsuggest
By default, requests that match no rules will receive an explanation of the +request & existing rules, followed by some suggested example Mockttp code +which could be used to match the rule.
+In some cases where the end client is unaware of Mockttp, these example
+suggestions are just confusing. Set suggestChanges to false to disable it.
Interface OngoingBody
asBuffer: (() => Promise<Buffer>);
asDecodedBuffer: (() => Promise<Buffer>);
asFormData: (() => Promise<{
[key: string]: string | string[] | undefined;
}>);
asJson: (() => Promise<object>);
asStream: (() => Readable);
asText: (() => Promise<string>);
}
Index
Properties
Properties
as
as
as
[key: string]: string | string[] | undefined;
}>)
as
as
as
Interface OngoingRequest
body: OngoingBody;
headers: Headers;
hostname?: string;
httpVersion?: string;
id: string;
matchedRuleId?: string;
method: string;
path: string;
protocol: string;
rawHeaders: RawHeaders;
rawTrailers?: RawHeaders;
remoteIpAddress?: string;
remotePort?: number;
tags: string[];
timingEvents: TimingEvents;
url: string;
}
Hierarchy (view full)
- Request
- EventEmitter
- OngoingRequest
Index
Properties
Properties
body
headers
Optionalhostname
Optionalhttp
id
Optionalmatched
method
path
protocol
raw
Optionalraw
Optionalremote
Optionalremote
tags
timing
url
Interface OngoingResponse
body: OngoingBody;
id: string;
tags: string[];
timingEvents: TimingEvents;
getHeaders(): Headers;
getRawHeaders(): RawHeaders;
getRawTrailers(): RawHeaders;
}
Hierarchy
- ServerResponse
- OngoingResponse
Index
Properties
Methods
Methods
get
- get
Headers(): Headers Returns a shallow copy of the current outgoing headers. Since a shallow +copy is used, array values may be mutated without additional calls to +various header-related HTTP module methods. The keys of the returned +object are the header names and the values are the respective header +values. All header names are lowercase.
+The object returned by the
+outgoingMessage.getHeaders()method does +not prototypically inherit from the JavaScriptObject. This means that +typicalObjectmethods such asobj.toString(),obj.hasOwnProperty(), +and others are not defined and will not work.
+ +outgoingMessage.setHeader('Foo', 'bar');
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
const headers = outgoingMessage.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } +Returns Headers
get
- get
Raw Headers(): RawHeaders Returns RawHeaders
get
- get
Raw Trailers(): RawHeaders Returns RawHeaders
Interface PassThroughHandlerConnectionOptions
This defines the upstream connection parameters. These passthrough parameters +are shared between both WebSocket & Request passthrough rules.
+additionalTrustedCAs?: CADefinition[];
clientCertificateHostMap?: {
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
};
forwarding?: ForwardingOptions;
ignoreHostHttpsErrors?: boolean | string[];
lookupOptions?: PassThroughLookupOptions;
proxyConfig?: ProxyConfig;
trustAdditionalCAs?: CADefinition[];
}
Hierarchy (view full)
- PassThroughHandlerConnectionOptions
Properties
Optionaladditional
An array of additional certificates, which should be trusted as certificate +authorities for upstream hosts, in addition to Node.js's built-in certificate +authorities.
+Each certificate should be an object with either a cert key and a string
+or buffer value containing the PEM certificate, or a certPath key and a
+string value containing the local path to the PEM certificate.
Optionalclient
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
}
A mapping of hosts to client certificates to use, in the form of
+{ key, cert } objects (none, by default)
Optionalforwarding
The forwarding configuration for the passthrough rule.
+This generally shouldn't be used explicitly unless you're
+building rule data by hand. Instead, call thenPassThrough
+to send data directly or thenForwardTo with options to
+configure traffic forwarding.
Optionalignore
A list of hostnames for which server certificate and TLS version errors +should be ignored (none, by default).
+If set to 'true', HTTPS errors will be ignored for all hosts. WARNING:
+Use this at your own risk. Setting this to true can open your
+application to MITM attacks and should never be used over any network
+that is not completed trusted end-to-end.
Optionallookup
Custom DNS options, to allow configuration of the resolver used +when forwarding requests upstream. Passing any option switches +from using node's default dns.lookup function to using the +cacheable-lookup module, which will cache responses.
+Optionalproxy
Upstream proxy configuration: pass through requests via this proxy.
+If this is undefined, no proxy will be used. To configure a proxy +provide either:
+-
+
- a ProxySettings object +
- a callback which will be called with an object containing the +hostname, and must return a ProxySettings object or undefined. +
- an array of ProxySettings or callbacks. The array will be +processed in order, and the first not-undefined ProxySettings +found will be used. +
When using a remote client, this parameter or individual array +values may be passed by reference, using the name of a rule +parameter configured in the admin server.
+Optionaltrust
Deprecated alias for additionalTrustedCAs
Interface AdminClientOptions
adminServerUrl?: string;
adminStreamReconnectAttempts?: number;
debug?: boolean;
requestOptions?: {
headers?: {
[key: string]: string;
};
};
}
Index
Properties
Properties
Optionaladmin
The full URL to use to connect to a Mockttp admin server when using a +remote (or local but browser) client.
+When using a local server, this option is ignored.
+Optionaladmin
If the admin stream disconnects, how many times should we try to +reconnect? Increasing this can be useful in unstable environments, such +as desktop app use case, while fewer retries will provide faster shutdown +in environments where you may be killing processes intentionally.
+Optionaldebug
Should the client print extra debug information?
+Optionalrequest
headers?: {
[key: string]: string;
};
}
Options to include on all client requests.
+Interface AdminPlugin<StartParams, ClientResponse>
buildResolvers: ((stream: Duplex, ruleParameters: {
[key: string]: any;
}) => IResolvers);
enableDebug?: (() => void);
reset?: (() => MaybePromise<void>);
schema: string | DocumentNode;
start: ((options: StartParams) => MaybePromise<ClientResponse>);
stop: (() => MaybePromise<void>);
}
Type Parameters
Implemented by
Index
Properties
Interface AdminQuery<Response, Result>
query: DocumentNode;
transformResponse?: ((result: Response, context: QueryContext) => MaybePromise<Result>);
variables?: {};
}
Type Parameters
- Response extends unknown
- Result extends unknown = Response
Index
Properties
Interface AdminServerOptions<Plugins>
corsOptions?: CorsOptions & {
allowPrivateNetworkAccess?: boolean;
strict?: boolean;
};
debug?: boolean;
pluginDefaults?: Partial<PluginStartParamsMap<Plugins>>;
ruleParameters?: {
[key: string]: any;
};
webSocketKeepAlive?: number;
}
Type Parameters
- Plugins extends {
[key: string]: AdminPlugin<any, any>;
}
Index
Properties
Properties
Optionalcors
allowPrivateNetworkAccess?: boolean;
strict?: boolean;
}
Set CORS options to limit the sites which can send requests to manage this admin server.
+Optionaldebug
Should the admin server print extra debug information? This enables admin server debugging +only - individual mock session debugging must be enabled separately.
+Optionalplugin
Override the default parameters for sessions started from this admin server. These values will be +used for each setting that is not explicitly specified by the client when creating a mock session.
+Optionalrule
[key: string]: any;
}
Some rule options can't easily be specified in remote clients, since they need to access
+server-side state or Node APIs directly. To handle this, referenceable parameters can
+be provided here, and referenced with a { [MOCKTTP_PARAM_REF]: <value> } value in place
+of the real parameter in the remote client.
Optionalweb
Set a keep alive frequency in milliseconds for the subscription & stream websockets of each +session, to ensure they remain connected in long-lived connections, especially in browsers which +often close quiet background connections automatically.
+Interface ProxyEnvConfig
Index
Properties
Interface ProxySetting
A ProxySetting is a specific proxy setting to use, which is passed to a proxy agent +who will manage creating a socket for the request (directly, or tunnelled, or whatever).
+additionalTrustedCAs?: CADefinition[];
noProxy?: string[];
proxyUrl: string;
trustedCAs?: (string | CADefinition)[];
}
Index
Properties
Properties
Optionaladditional
Extra CAs to trust for HTTPS connections to the proxy. Ignored if the connection +to the proxy is not HTTPS.
+This appends to the list of trusted CAs, and is mutually exclusive with the
+trustedCAs option, which completely overrides the list of CAs.
Optionalno
A list of no-proxy values, matching hosts' traffic should not be proxied.
+This is a common proxy feature, but unfortunately isn't standardized. See +https://about.gitlab.com/blog/2021/01/27/we-need-to-talk-no-proxy/ for some +background. This implementation is intended to match Curl's behaviour, and +any differences are a bug.
+The currently supported formats are:
+-
+
- example.com (matches domain and all subdomains) +
- example.com:443 (matches domain and all subdomains, but only on that port) +
- 10.0.0.1 (matches IP, but only when used directly - does not resolve domains) +
Some other formats (e.g. leading dots or *.) will work, but the leading +characters are ignored. More formats may be added in future, e.g. CIDR ranges. +To maximize compatibility with values used elsewhere, unrecognized formats +will generally be ignored, but may match in unexpected ways.
+proxy
The URL for the proxy to forward traffic through.
+This can be any URL supported by https://www.npmjs.com/package/proxy-agent. +For example: http://..., socks5://..., pac+http://...
+OptionaltrustedCAs
CAs to trust for HTTPS connections to the proxy. Ignored if the connection to +the proxy is not HTTPS. If not specified, this will default to the Node +defaults, or you can override them here completely.
+This sets the complete list of trusted CAs, and is mutually exclusive with the
+additionalTrustedCAs option, which adds additional CAs (but also trusts the
+Node default CAs too).
This should be specified as either a { cert: string | Buffer } object or a +{ certPath: string } object (to read the cert from disk). The previous +simple string format is supported but deprecated.
+Interface Request
headers: Headers;
hostname?: string;
httpVersion?: string;
id: string;
matchedRuleId?: string;
method: string;
path: string;
protocol: string;
rawHeaders: RawHeaders;
remoteIpAddress?: string;
remotePort?: number;
tags: string[];
timingEvents: TimingEvents;
url: string;
}
Hierarchy (view full)
Index
Properties
Properties
headers
Optionalhostname
Optionalhttp
id
Optionalmatched
method
path
protocol
raw
Optionalremote
Optionalremote
tags
timing
url
Interface RequestRuleData
completionChecker?: RuleCompletionChecker;
handler: RequestHandlerDefinition | RequestHandler;
id?: string;
matchers: RequestMatcher[];
priority?: number;
}
Index
Properties
Interface TimingEvents
abortedTimestamp?: number;
bodyReceivedTimestamp?: number;
headersSentTimestamp?: number;
responseSentTimestamp?: number;
startTime: number;
startTimestamp: number;
wsAcceptedTimestamp?: number;
wsClosedTimestamp?: number;
}
Properties
Optionalaborted
Optionalbody
Optionalheaders
Optionalresponse
start
start
Optionalws
Optionalws
Interface TlsConnectionEvent
hostname?: string;
remoteIpAddress: string;
remotePort: number;
tags: string[];
timingEvents: TlsTimingEvents;
tlsMetadata: TlsSocketMetadata;
}
Hierarchy (view full)
- TlsConnectionEvent
Index
Properties
Interface TlsFailureTimingEvents
connectTimestamp: number;
disconnectTimestamp?: number;
failureTimestamp: number;
handshakeTimestamp?: number;
startTime: number;
tunnelTimestamp?: number;
}
Hierarchy (view full)
- TlsTimingEvents
- TlsFailureTimingEvents
Index
Properties
connect
When the socket initially connected, equivalent to startTime.
+High-precision floating-point monotonically increasing timestamps. +Comparable and precise, but not related to specific current time.
+Optionaldisconnect
When the connection was closed, if it has been closed.
+failure
When the TLS connection failed. This may be due to a failed handshake
+(in which case handshakeTimestamp will be undefined) or due to a
+subsequent error which means the TLS connection was not usable (like
+an immediate closure due to an async certificate rejection).
Optionalhandshake
When Mockttp's handshake for this connection was completed (if there +was one). This is not set for passed through connections.
+start
When the socket initially connected, in MS since the unix +epoch.
+Optionaltunnel
When the outer tunnel (e.g. a preceeding CONNECT request) was created, +if there was one.
+Interface TlsPassthroughEvent
hostname?: string;
id: string;
remoteIpAddress: string;
remotePort: number;
tags: string[];
timingEvents: TlsTimingEvents;
tlsMetadata: TlsSocketMetadata;
upstreamPort: number;
}
Hierarchy (view full)
- TlsConnectionEvent
- TlsPassthroughEvent
Index
Properties
Interface TlsRequest
failureCause:
| "closed"
| "reset"
| "unknown"
| "cert-rejected"
| "no-shared-cipher"
| "handshake-timeout";
hostname?: string;
remoteIpAddress: string;
remotePort: number;
tags: string[];
timingEvents: TlsFailureTimingEvents;
tlsMetadata: TlsSocketMetadata;
}
Hierarchy (view full)
- TlsConnectionEvent
- TlsRequest
Index
Properties
Interface TlsSocketMetadata
clientAlpn?: string[];
connectHostname?: string;
connectPort?: string;
ja3Fingerprint?: string;
sniHostname?: string;
}
Index
Properties
Interface TlsTimingEvents
connectTimestamp: number;
disconnectTimestamp?: number;
handshakeTimestamp?: number;
startTime: number;
tunnelTimestamp?: number;
}
Hierarchy (view full)
- TlsTimingEvents
Index
Properties
Properties
connect
When the socket initially connected, equivalent to startTime.
+High-precision floating-point monotonically increasing timestamps. +Comparable and precise, but not related to specific current time.
+Optionaldisconnect
When the connection was closed, if it has been closed.
+Optionalhandshake
When Mockttp's handshake for this connection was completed (if there +was one). This is not set for passed through connections.
+start
When the socket initially connected, in MS since the unix +epoch.
+Optionaltunnel
When the outer tunnel (e.g. a preceeding CONNECT request) was created, +if there was one.
+Interface Trailers
Indexable
- [key: string]: undefined | string | string[]
Interface WebSocketClose
closeCode: undefined | number;
closeReason: string;
streamId: string;
tags: string[];
timingEvents: TimingEvents;
}
Index
Properties
Properties
close
The close code of the shutdown. This is the close code that was received +from the remote client (either initiated remotely, or echoing our own sent +close frame).
+This may be undefined only if a close frame was received but did not contain +any close code. If no close frame was received before the connection was +lost (i.e. the connection was not cleanly closed) this event will not +fire at all, and an 'abort' event will fire instead.
+close
The close reason of the shutdown.
+stream
The id of this websocket stream. This will match the id of the request, +the initial connection response, and any other WebSocket events for the +same connection stream.
+tags
timing
Interface WebSocketMessage
content: Uint8Array;
direction: "sent" | "received";
eventTimestamp: number;
isBinary: boolean;
streamId: string;
tags: string[];
timingEvents: TimingEvents;
}
Index
Properties
Properties
content
The contents of the message as a raw buffer. This is already decompressed, +if the WebSocket uses compression.
+direction
Whether the message was sent by Mockttp, or received from a Mockttp client.
+event
A high-precision floating-point monotonically increasing timestamp. +Comparable and precise, but not related to specific current time.
+To link this to the current time, compare it to timingEvents.startTime.
is
Whether this is a string message or a raw binary data message.
+stream
The id of this websocket stream. This will match the id of the request, +the initial connection response, and any other WebSocket events for the +same connection stream.
+tags
timing
Interface WebSocketRuleData
completionChecker?: RuleCompletionChecker;
handler: WebSocketHandlerDefinition | WebSocketHandler;
id?: string;
matchers: RequestMatcher[];
priority?: number;
}
Index
Properties
Interface RuleCompletionChecker
type:
| "once"
| "always"
| "twice"
| "thrice"
| "times";
dispose(): void;
explain(seenRequestCount: undefined | number): string;
isComplete(seenRequestCount: number): boolean;
}
Hierarchy (view full)
- Serializable
- RuleCompletionChecker
Implemented by
Index
Properties
Methods
Interface RequestMatcher
type:
| "port"
| "header"
| "method"
| "host"
| "query"
| "protocol"
| "hostname"
| "cookie"
| "callback"
| "wildcard"
| "simple-path"
| "regex-path"
| "regex-url"
| "exact-query-string"
| "form-data"
| "multipart-form-data"
| "raw-body"
| "raw-body-regexp"
| "raw-body-includes"
| "json-body"
| "json-body-matching";
dispose(): void;
explain(): string;
matches(request: OngoingRequest): MaybePromise<boolean>;
}
Hierarchy (view full)
- Explainable
- Serializable
- RequestMatcher
Implemented by
- CallbackMatcher
- CookieMatcher
- ExactQueryMatcher
- FormDataMatcher
- HeaderMatcher
- HostMatcher
- HostnameMatcher
- JsonBodyFlexibleMatcher
- JsonBodyMatcher
- MethodMatcher
- MultipartFormDataMatcher
- PortMatcher
- ProtocolMatcher
- QueryMatcher
- RawBodyIncludesMatcher
- RawBodyMatcher
- RegexBodyMatcher
- RegexPathMatcher
- RegexUrlMatcher
- SimplePathMatcher
- WildcardMatcher
Properties
type
| "port"
| "header"
| "method"
| "host"
| "query"
| "protocol"
| "hostname"
| "cookie"
| "callback"
| "wildcard"
| "simple-path"
| "regex-path"
| "regex-url"
| "exact-query-string"
| "form-data"
| "multipart-form-data"
| "raw-body"
| "raw-body-regexp"
| "raw-body-includes"
| "json-body"
| "json-body-matching"
Methods
dispose
explain
matches
- matches(request): MaybePromise<boolean>
Parameters
- request: OngoingRequest
Returns MaybePromise<boolean>
Interface RequestHandlerDefinition
type:
| "file"
| "stream"
| "timeout"
| "callback"
| "simple"
| "passthrough"
| "close-connection"
| "reset-connection"
| "json-rpc-response";
dispose(): void;
explain(): string;
}
Hierarchy (view full)
- Explainable
- Serializable
- RequestHandlerDefinition
Implemented by
Interface CallbackRequestResult
Can be returned from callbacks to override parts of a request.
+All fields are optional, and omitted values will default to the original +request value.
+body?: string | Uint8Array | Buffer;
headers?: Headers;
json?: any;
method?: string;
rawBody?: Uint8Array | Buffer;
response?: CallbackResponseResult;
url?: string;
}
Properties
Optionalbody
A string or buffer, which replaces the request body if set. This will +be automatically content-encoded to match the Content-Encoding defined +in your request headers.
+If this is set, the Content-Length header will be automatically updated
+accordingly to match, unless you also provide a headers value that
+includes a Content-Length header, in which case that will take used
+as-is.
You should only return one body field: either body, rawBody or
+json.
Optionalheaders
The replacement HTTP headers, as an object of string keys and either +single string or array of string values.
+Optionaljson
A JSON value, which will be stringified and send as a JSON-encoded +request body. This will be automatically content-encoded to match +the Content-Encoding defined in your request headers.
+If this is set, the Content-Length header will be automatically updated
+accordingly to match, unless you also provide a headers value that
+includes a Content-Length header, in which case that will take used
+as-is.
You should only return one body field: either body, rawBody or
+json.
Optionalmethod
A replacement HTTP method, capitalized.
+Optionalraw
A buffer, which replaces the request body if set, which is sent exactly +as is, and is not automatically encoded.
+If this is set, the Content-Length header will be automatically updated
+accordingly to match, unless you also provide a headers value that
+includes a Content-Length header, in which case that will take used
+as-is.
You should only return one body field: either body, rawBody or
+json.
Optionalresponse
A response: either a response object defining the fields of a response +or the string 'close' to immediately close the connection.
+See CallbackResponseMessageResult for the possible fields that can +be set to define the response.
+If set, the request will not be forwarded at all, and this will be used +as the response to immediately return to the client (or for 'close', this +will immediately close the connection to the client).
+Optionalurl
The full URL to send the request to. If set, this will redirect
+the request and automatically update the Host header accordingly,
+unless you also provide a headers value that includes a Host
+header, in which case that will take used as-is.
Interface CallbackResponseMessageResult
Can be returned from callbacks to define parts of a response, or +override parts when given an existing repsonse.
+All fields are optional, and omitted values will default to the original +response value or a default value.
+body?: string | Uint8Array | Buffer;
headers?: Headers;
json?: any;
rawBody?: Uint8Array | Buffer;
status?: number;
statusCode?: number;
statusMessage?: string;
trailers?: Trailers;
}
Index
Properties
Properties
Optionalbody
A string or buffer, which replaces the response body if set. This will +be automatically encoded to match the Content-Encoding defined in your +response headers.
+If this is set, the Content-Length header will be automatically updated
+accordingly to match, unless you also provide a headers value that
+includes a Content-Length header, in which case that will take used
+as-is.
Defaults to empty.
+You should only return one body field: either body, rawBody or
+json.
Optionalheaders
The replacement HTTP headers, as an object of string keys and either +single string or array of string values.
+Defaults to a minimum set of standard required headers if not set.
+Optionaljson
A JSON value, which will be stringified and send as a JSON-encoded +request body. This will be automatically content-encoded to match the +Content-Encoding defined in your response headers.
+If this is set, the Content-Length header will be automatically updated
+accordingly to match, unless you also provide a headers value that
+includes a Content-Length header, in which case that will take used
+as-is.
You should only return one body field: either body, rawBody or
+json.
Optionalraw
A buffer, which replaces the response body if set, which is sent exactly +as is, and is not automatically encoded.
+If this is set, the Content-Length header will be automatically updated
+accordingly to match, unless you also provide a headers value that
+includes a Content-Length header, in which case that will take used
+as-is.
You should only return one body field: either body, rawBody or
+json.
Optionalstatus
Supported only for backward compatibility.
+Optionalstatus
The response status code as a number.
+Defaults to 200 if not set.
+Optionalstatus
The response status message, as a string. This is ignored for +HTTP/2 responses.
+Defaults to the default status message for the status code if not set.
+Optionaltrailers
The replacement HTTP trailers, as an object of string keys and either +single string or array of string values. Note that there are not all +header fields are valid as trailers, and there are other requirements +such as chunked encoding that must be met for trailers to be sent +successfully.
+Interface ForwardingOptions
Index
Properties
Interface PassThroughHandlerOptions
This defines the upstream connection parameters. These passthrough parameters +are shared between both WebSocket & Request passthrough rules.
+additionalTrustedCAs?: CADefinition[];
beforeRequest?: ((req: CompletedRequest) => MaybePromise<void | CallbackRequestResult>);
beforeResponse?: ((res: PassThroughResponse) => MaybePromise<void | CallbackResponseResult>);
clientCertificateHostMap?: {
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
};
forwarding?: ForwardingOptions;
ignoreHostHttpsErrors?: boolean | string[];
lookupOptions?: PassThroughLookupOptions;
proxyConfig?: ProxyConfig;
simulateConnectionErrors?: boolean;
transformRequest?: RequestTransform;
transformResponse?: ResponseTransform;
trustAdditionalCAs?: CADefinition[];
}
Hierarchy (view full)
- PassThroughHandlerConnectionOptions
- PassThroughHandlerOptions
Properties
Optionaladditional
An array of additional certificates, which should be trusted as certificate +authorities for upstream hosts, in addition to Node.js's built-in certificate +authorities.
+Each certificate should be an object with either a cert key and a string
+or buffer value containing the PEM certificate, or a certPath key and a
+string value containing the local path to the PEM certificate.
Optionalbefore
A callback that will be passed the full request before it is passed through, +and which returns an object that defines how the the request content should +be transformed before it's passed to the upstream server.
+The callback can return an object to define how the request should be changed. +All fields on the object are optional, and returning undefined is equivalent +to returning an empty object (transforming nothing).
+See CallbackRequestResult for the possible fields that can be set.
+Optionalbefore
A callback that will be passed the full response before it is passed through, +and which returns a value that defines how the the response content should +be transformed before it's returned to the client.
+The callback can either return an object to define how the response should be +changed, or the string 'close' to immediately close the underlying connection.
+All fields on the object are optional, and returning undefined is equivalent +to returning an empty object (transforming nothing).
+See CallbackResponseMessageResult for the possible fields that can be set.
+Optionalclient
[host: string]: {
passphrase?: string;
pfx: Buffer;
};
}
A mapping of hosts to client certificates to use, in the form of
+{ key, cert } objects (none, by default)
Optionalforwarding
The forwarding configuration for the passthrough rule.
+This generally shouldn't be used explicitly unless you're
+building rule data by hand. Instead, call thenPassThrough
+to send data directly or thenForwardTo with options to
+configure traffic forwarding.
Optionalignore
A list of hostnames for which server certificate and TLS version errors +should be ignored (none, by default).
+If set to 'true', HTTPS errors will be ignored for all hosts. WARNING:
+Use this at your own risk. Setting this to true can open your
+application to MITM attacks and should never be used over any network
+that is not completed trusted end-to-end.
Optionallookup
Custom DNS options, to allow configuration of the resolver used +when forwarding requests upstream. Passing any option switches +from using node's default dns.lookup function to using the +cacheable-lookup module, which will cache responses.
+Optionalproxy
Upstream proxy configuration: pass through requests via this proxy.
+If this is undefined, no proxy will be used. To configure a proxy +provide either:
+-
+
- a ProxySettings object +
- a callback which will be called with an object containing the +hostname, and must return a ProxySettings object or undefined. +
- an array of ProxySettings or callbacks. The array will be +processed in order, and the first not-undefined ProxySettings +found will be used. +
When using a remote client, this parameter or individual array +values may be passed by reference, using the name of a rule +parameter configured in the admin server.
+Optionalsimulate
Whether to simulate connection errors back to the client.
+By default (in most cases - see below) when an upstream request fails +outright a 502 "Bad Gateway" response is sent to the downstream client, +explicitly indicating the failure and containing the error that caused +the issue in the response body.
+Only in the case of upstream connection reset errors is a connection reset +normally sent back downstream to existing clients (this behaviour exists +for backward compatibility, and will change to match other error behaviour +in a future version).
+When this option is set to true, low-level connection failures will
+always trigger a downstream connection close/reset, rather than a 502
+response.
This includes DNS failures, TLS connection errors, TCP connection resets, +etc (but not HTTP non-200 responses, which are still proxied as normal). +This is less convenient for debugging in a testing environment or when +using a proxy intentionally, but can be more accurate when trying to +transparently proxy network traffic, errors and all.
+Optionaltransform
A set of data to automatically transform a request. This includes properties +to support many transformation common use cases.
+For advanced cases, a custom callback using beforeRequest can be used instead. +Using this field however where possible is typically simpler, more declarative, +and can be more performant. The two options are mutually exclusive: you cannot +use both transformRequest and a beforeRequest callback.
+Only one transformation for each target (method, headers & body) can be +specified. If more than one is specified then an error will be thrown when the +rule is registered.
+Optionaltransform
A set of data to automatically transform a response. This includes properties +to support many transformation common use cases.
+For advanced cases, a custom callback using beforeResponse can be used instead. +Using this field however where possible is typically simpler, more declarative, +and can be more performant. The two options are mutually exclusive: you cannot +use both transformResponse and a beforeResponse callback.
+Only one transformation for each target (status, headers & body) can be +specified. If more than one is specified then an error will be thrown when the +rule is registered.
+Optionaltrust
Deprecated alias for additionalTrustedCAs
Interface PassThroughLookupOptions
Properties
Optionalerror
How long to cache a DNS ENODATA or ENOTFOUND response. Defaults +to 0.15.
+Optionalmax
The maximum time to cache a DNS response. Up to this limit, +responses will be cached according to their own TTL. Defaults +to Infinity.
+Optionalservers
The primary servers to use. DNS queries will be resolved against +these servers first. If no data is available, queries will fall +back to dns.lookup, and use the OS's default DNS servers.
+This defaults to dns.getServers().
+Interface PassThroughResponse
body: CompletedBody;
headers: Headers;
id: string;
rawHeaders: RawHeaders;
statusCode: number;
statusMessage?: string;
}
Index
Properties
Interface RequestHandler
type:
| "file"
| "stream"
| "timeout"
| "callback"
| "simple"
| "passthrough"
| "close-connection"
| "reset-connection"
| "json-rpc-response";
dispose(): void;
explain(): string;
handle(request: OngoingRequest, response: OngoingResponse, options: RequestHandlerOptions): Promise<void>;
}
Hierarchy (view full)
- RequestHandlerDefinition
- RequestHandler
Properties
type
| "file"
| "stream"
| "timeout"
| "callback"
| "simple"
| "passthrough"
| "close-connection"
| "reset-connection"
| "json-rpc-response"
Methods
dispose
explain
handle
- handle(request, response, options): Promise<void>
Parameters
- request: OngoingRequest
- response: OngoingResponse
- options: RequestHandlerOptions
Returns Promise<void>
Interface RequestHandlerOptions
Index
Properties
Interface RequestTransform
matchReplaceBody?: [string | RegExp, string][];
patchJsonBody?: Operation[];
replaceBody?: string | Uint8Array | Buffer;
replaceBodyFromFile?: string;
replaceHeaders?: Headers;
replaceMethod?: string;
updateHeaders?: Headers;
updateJsonBody?: {
[key: string]: any;
};
}
Index
Properties
Optionalmatch
Perform a series of string match & replace operations on the request body.
+This parameter should be an array of pairs, which will be applied to the body
+decoded as a string like body.replace(p1, p2), applied in the order provided.
+The first parameter can be either a string or RegExp to match, and the second
+must be a string to insert. The normal str.replace $ placeholders can be
+used in the second argument, so that e.g. $1 will insert the 1st matched group.
Optionalpatch
A series of operations to apply to the request body in JSON Patch format (RFC +6902).
+Any requests which are received with an invalid JSON body that match this rule +will fail.
+Optionalreplace
A string or buffer that replaces the request body entirely.
+If this is specified, the upstream request will not wait for the original request +body, so this may make responses faster than they would be otherwise given large +request bodies or slow/streaming clients.
+Optionalreplace
The path to a file, which will be used to replace the request body entirely. The +file will be re-read for each request, so the body will always reflect the latest +file contents.
+If this is specified, the upstream request will not wait for the original request +body, so this may make responses faster than they would be otherwise given large +request bodies or slow/streaming clients.
+Optionalreplace
A headers object which will completely replace the real request headers.
+Optionalreplace
A replacement HTTP method. Case insensitive.
+Optionalupdate
A headers object which will be merged with the real request headers to add or +replace values. Headers with undefined values will be removed.
+Optionalupdate
[key: string]: any;
}
A JSON object which will be merged with the real request body. Undefined values +will be removed, and other values will be merged directly with the target value +recursively.
+Any requests which are received with an invalid JSON body that match this rule +will fail.
+Interface ResponseTransform
matchReplaceBody?: [string | RegExp, string][];
patchJsonBody?: Operation[];
replaceBody?: string | Uint8Array | Buffer;
replaceBodyFromFile?: string;
replaceHeaders?: Headers;
replaceStatus?: number;
updateHeaders?: Headers;
updateJsonBody?: {
[key: string]: any;
};
}
Index
Properties
Optionalmatch
Perform a series of string match & replace operations on the response body.
+This parameter should be an array of pairs, which will be applied to the body
+decoded as a string like body.replace(p1, p2), applied in the order provided.
+The first parameter can be either a string or RegExp to match, and the second
+must be a string to insert. The normal str.replace $ placeholders can be
+used in the second argument, so that e.g. $1 will insert the 1st matched group.
Optionalpatch
A series of operations to apply to the response body in JSON Patch format (RFC +6902).
+Any responses which are received with an invalid JSON body that match this rule +will fail.
+Optionalreplace
A string or buffer that replaces the response body entirely.
+If this is specified, the downstream response will not wait for the original response +body, so this may make responses arrive faster than they would be otherwise given large +response bodies or slow/streaming servers.
+Optionalreplace
The path to a file, which will be used to replace the response body entirely. The +file will be re-read for each response, so the body will always reflect the latest +file contents.
+If this is specified, the downstream response will not wait for the original response +body, so this may make responses arrive faster than they would be otherwise given large +response bodies or slow/streaming servers.
+Optionalreplace
A headers object which will completely replace the real response headers.
+Optionalreplace
A replacement response status code.
+Optionalupdate
A headers object which will be merged with the real response headers to add or +replace values. Headers with undefined values will be removed.
+Optionalupdate
[key: string]: any;
}
A JSON object which will be merged with the real response body. Undefined values +will be removed, and other values will be merged directly with the target value +recursively.
+Any responses which are received with an invalid JSON body that match this rule +will fail.
+Interface WebSocketHandlerDefinition
type:
| "timeout"
| "close-connection"
| "reset-connection"
| "ws-passthrough"
| "ws-echo"
| "ws-listen"
| "ws-reject";
dispose(): void;
explain(): string;
}
Hierarchy (view full)
- Explainable
- Serializable
- WebSocketHandlerDefinition
Implemented by
Interface WebSocketHandler
type:
| "timeout"
| "close-connection"
| "reset-connection"
| "ws-passthrough"
| "ws-echo"
| "ws-listen"
| "ws-reject";
dispose(): void;
explain(): string;
handle(request: OngoingRequest & IncomingMessage, socket: Socket, head: Buffer): Promise<void>;
}
Hierarchy (view full)
- WebSocketHandlerDefinition
- WebSocketHandler
Properties
type
| "timeout"
| "close-connection"
| "reset-connection"
| "ws-passthrough"
| "ws-echo"
| "ws-listen"
| "ws-reject"
Methods
dispose
explain
handle
- handle(request, socket, head): Promise<void>
Parameters
- request: OngoingRequest & IncomingMessage
- socket: Socket
- head: Buffer
Returns Promise<void>
mockttp
Index
Internal
Other
Other
Cert
Renames and re-exports HttpsOptionsCert
Renames and re-exports HttpsPathOptionsForwarding
Re-exports ForwardingOptionsPass
Re-exports PassThroughLookupOptionsTls
Renames and re-exports TlsRequestNamespace MockttpPluggableAdmin
This API is not yet stable, and is intended for internal use only. It may change in future +in minor versions without warning.
+These plugin components can be applied to the PluggableAdmin API to create a remotely +controlable mock management server that can mock HTTP in addition to protocols from +other plugins.
+Index
Classes
Interfaces
Namespace Serialization
Index
References
Classes
Type Aliases
Functions
References
Serialized
Re-exports SerializedSerialized
Re-exports SerializedValueNamespace PluggableAdmin
This API is not yet stable, and is intended for internal use only. It may change in future +in minor versions without warning.
+These generic pluggable admin components allow composing an admin server and client that +are capable of managing arbitrary mock protocols, including Mockttp but also others depending +on the admin plugins used. To use Mockttp, combine this with the MockttpPluggableAdmin API.
+Index
Namespaces
Classes
Interfaces
Type Aliases
Namespace completionCheckers
Index
Classes
Interfaces
Variables
Namespace matchers
Index
Classes
Interfaces
Type Aliases
Variables
Functions
Namespace requestHandlerDefinitions
Index
References
Classes
Interfaces
Type Aliases
Variables
References
Callback
Re-exports CallbackRequestResultCallback
Re-exports CallbackResponseMessageResultCallback
Re-exports CallbackResponseResultPass
Re-exports PassThroughHandlerOptionsPass
Re-exports PassThroughResponseRequest
Re-exports RequestTransformResponse
Re-exports ResponseTransformNamespace requestHandlers
Index
Classes
Interfaces
Type Aliases
Variables
Namespace webSocketHandlerDefinitions
Index
References
Classes
Interfaces
Variables
References
Close
Re-exports CloseConnectionHandlerDefinitionPass
Re-exports PassThroughWebSocketHandlerOptionsReset
Re-exports ResetConnectionHandlerDefinitionTimeout
Re-exports TimeoutHandlerDefinitionNamespace webSocketHandlers
Index
References
Classes
Interfaces
Type Aliases
Variables
References
Close
Re-exports CloseConnectionHandlerReset
Re-exports ResetConnectionHandlerTimeout
Re-exports TimeoutHandlerType Alias CADefinition
cert: string | Buffer;
} | {
certPath: string;
}
Type Alias CAOptions
Type Alias DnsLookupFunction
Type Alias InitiatedRequest
Type Alias MockttpHttpsOptions
defaultDomain?: string;
tlsInterceptOnly?: {
hostname: string;
}[];
tlsPassthrough?: {
hostname: string;
}[];
}
Type declaration
OptionaldefaultDomain?: string The domain name that will be used in the certificate for incoming TLS +connections which don't use SNI to request a specific domain.
+OptionaltlsIntercept Only?: {
hostname: string;
}[]A limited list of the only hostnames whose TLS should be intercepted.
+This is the opposite of
+tlsPassthrough. When set, only connections +to these hostnames will be intercepted, and all other TLS connections will +be passed through without interception.This option is mutually exclusive with
+tlsPassthroughand setting both +options will throw an error.Each element in this list must be an object with a 'hostname' field for the +hostname that should be matched. Wildcards are supported (following the +URLPattern specification), +eg.
+{hostname: '*.example.com'}.In future more options may be supported +here for additional configuration of this behaviour.
+OptionaltlsPassthrough?: {
hostname: string;
}[]A list of hostnames where TLS interception should always be skipped.
+When a TLS connection is started that references a matching hostname in its +server name indication (SNI) extension, or which uses a matching hostname +in a preceeding CONNECT request to create a tunnel, the connection will be +sent raw to the upstream hostname, without handling TLS within Mockttp (i.e. +with no TLS interception performed).
+This option is mutually exclusive with
+tlsInterceptOnlyand setting both +options will throw an error.Each element in this list must be an object with a 'hostname' field for the +hostname that should be matched. Wildcards are supported (following the +URLPattern specification), +eg.
+{hostname: '*.example.com'}.In future more options may be supported +here for additional configuration of this behaviour.
+
Type Alias PEM
| string
| string[]
| Buffer
| Buffer[]
Type Alias PluginClientResponse<Plugin>
? ClientResponse
: never
Type Parameters
Type Alias PluginClientResponsesMap<Plugins>
Type Parameters
Type Alias PluginStartParams<Plugin>
Type Parameters
Type Alias PluginStartParamsMap<Plugins>
Type Parameters
Type Alias SerializedProxyConfig
| ProxySetting
| string
| undefined
| SerializedRuleParameterReference<ProxySettingSource>
| SerializedProxyConfig[]
Type Alias SerializedRuleParameterReference<R>
Type Parameters
Type Alias PortRange
endPort: number;
startPort: number;
}
Type Alias ProxyConfig
A ProxyConfig is externally provided config that specifies a ProxySettingSource. +It might be a ProxySettingSource itself, or it might include references to rule +parameters, which must be dereferenced to make it usable as a ProxySettingSource.
+Type Alias ProxySettingCallback
Type Alias ProxySettingCallbackParams
hostname: string;
}
Type Alias ProxySettingSource
A ProxySettingSource is a way to calculate the ProxySetting for a given request. It +may be a fixed ProxySetting value, or a callback to get ProxySetting values, or an +array of sources, which should be iterated to get the first usable value
+Type Alias RawHeaders
Type Alias RawTrailers
Type Alias RuleParameterReference<R>
A reference to a rule parameter defined in the ruleParameters admin server
+option of the corresponding admin server.
Rule parameter references are only valid with a remote client. They can be useful in +cases where the admin server has access to local state or APIs that are not +accessible from the remote client, but which would be useful in rule definitions. This +is only supported for some specific parameters where documented explicitly in that rule +parameter.
+Type Parameters
Type Alias RuleParameters
[key: string]: unknown;
}
Type Alias Serialized<T>
[K in keyof T]: T[K] extends string | undefined
? string | undefined
: T[K] extends unknown[]
? SerializedValue<T[K][0]>[]
: SerializedValue<T[K]>
}
Type Parameters
Type Alias SubscribableEvent
| "request-initiated"
| "request"
| "response"
| "websocket-request"
| "websocket-accepted"
| "websocket-message-received"
| "websocket-message-sent"
| "websocket-close"
| "abort"
| "tls-passthrough-opened"
| "tls-passthrough-closed"
| "tls-client-error"
| "client-error"
| "rule-event"
Type Alias defaultMaxListeners
Type Alias MultipartFieldMatchCondition
content?: string | Uint8Array;
filename?: string;
name?: string;
}
Type Alias SerializedBuffer
data: number[];
type: "Buffer";
}
Type Alias CallbackResponseResult
Type Alias PassThroughWebSocketHandlerOptions
Variable DEFAULT_ADMIN_SERVER_PORTConst
Variable MOCKTTP_PARAM_REFConst
Variable MatcherLookupConst
callback: typeof CallbackMatcher;
cookie: typeof CookieMatcher;
exact-query-string: typeof ExactQueryMatcher;
form-data: typeof FormDataMatcher;
header: typeof HeaderMatcher;
host: typeof HostMatcher;
hostname: typeof HostnameMatcher;
json-body: typeof JsonBodyMatcher;
json-body-matching: typeof JsonBodyFlexibleMatcher;
method: typeof MethodMatcher;
multipart-form-data: typeof MultipartFormDataMatcher;
port: typeof PortMatcher;
protocol: typeof ProtocolMatcher;
query: typeof QueryMatcher;
raw-body: typeof RawBodyMatcher;
raw-body-includes: typeof RawBodyIncludesMatcher;
raw-body-regexp: typeof RegexBodyMatcher;
regex-path: typeof RegexPathMatcher;
regex-url: typeof RegexUrlMatcher;
simple-path: typeof SimplePathMatcher;
wildcard: typeof WildcardMatcher;
} = ...
Variable HandlerDefinitionLookupConst
callback: typeof CallbackHandlerDefinition;
close-connection: typeof CloseConnectionHandlerDefinition;
file: typeof FileHandlerDefinition;
json-rpc-response: typeof JsonRpcResponseHandlerDefinition;
passthrough: typeof PassThroughHandlerDefinition;
reset-connection: typeof ResetConnectionHandlerDefinition;
simple: typeof SimpleHandlerDefinition;
stream: typeof StreamHandlerDefinition;
timeout: typeof TimeoutHandlerDefinition;
} = ...
Variable HandlerLookupConst
Variable WsHandlerDefinitionLookupConst
close-connection: typeof CloseConnectionHandlerDefinition;
reset-connection: typeof ResetConnectionHandlerDefinition;
timeout: typeof TimeoutHandlerDefinition;
ws-echo: typeof EchoWebSocketHandlerDefinition;
ws-listen: typeof ListenWebSocketHandlerDefinition;
ws-passthrough: typeof PassThroughWebSocketHandlerDefinition;
ws-reject: typeof RejectWebSocketHandlerDefinition;
} = ...
Subscribe to hear when each mock ession is started. The listener is provided the +session plugin data, which can be used to log session startup, add side-effects that +run elsewhere at startup, or preconfigure every started plugin in addition ways.
+This is run synchronously when a session is created, after it has fully started +but before its been returned to remote clients.
+