msw
- Version 3.0.0
- Published
- 3.34 MB
- 12 dependencies
- MIT license
Install
npm i mswyarn add mswpnpm add mswOverview
Seamless REST/GraphQL API mocking library for browser and Node.js.
Index
Variables
Functions
Classes
Interfaces
Enums
Type Aliases
- AnyHandler
- AsyncResponseResolverReturnType
- DefaultBodyType
- DefaultRequestMultipartBody
- DelayMode
- HttpCustomPredicate
- HttpHandlerMethod
- HttpRequestHandler
- HttpRequestParsedResult
- HttpRequestResolverExtras
- HttpResponseResolver
- JsonBodyType
- Path
- PathParams
- RequestQuery
- ResponseResolver
- ResponseResolverInfo
- ResponseResolverReturnType
- ServerSentEventMessage
- ServerSentEventRequestHandler
- ServerSentEventResolver
- ServerSentEventResolverExtras
- UnhandledFrameHandle
- UnhandledFrameStrategy
- WebSocketEventListener
- WebSocketHandlerEventMap
- WebSocketLink
Namespaces
Variables
variable http
const http: { all: HttpRequestHandler; head: HttpRequestHandler; get: HttpRequestHandler; post: HttpRequestHandler; put: HttpRequestHandler; delete: HttpRequestHandler; patch: HttpRequestHandler; options: HttpRequestHandler;};A namespace to intercept and mock HTTP requests.
Example 1
http.get('/user', resolver) http.post('/post/:id', resolver)
See Also
variable sse
const sse: ServerSentEventRequestHandler;Intercept Server-Sent Events (SSE).
Example 1
sse('http://localhost:4321', ({ client }) => { client.send({ data: 'hello world' }) })
See Also
variable WebSocketLinkOptions
const WebSocketLinkOptions: any;variable ws
const ws: WebSocketNamespace;A namespace to intercept and mock WebSocket connections.
Example 1
const chat = ws.link('wss://chat.example.com')
See Also
Functions
function bypass
bypass: (input: BypassRequestInput, init?: RequestInit) => Request;Creates a
Requestinstance that will always be ignored by MSW.Example 1
import { bypass } from 'msw'
fetch(bypass('/resource')) fetch(bypass(new URL('/resource', 'https://example.com))) fetch(bypass(new Request('https://example.com/resource')))
See Also
function delay
delay: (durationOrMode?: DelayMode | number) => Promise<void>;Delays the response by the given duration (ms).
Example 1
await delay() // emulate realistic server response time await delay(1200) // delay response by 1200ms await delay('infinite') // delay response infinitely
See Also
function getCleanUrlString
getCleanUrlString: (url: string) => string;Removes search parameters and the fragment from a given URL string. Unlike
getCleanUrl()from Interceptors, accepts relative URLs and path patterns (e.g. "/user/:id?") since it never parses the input as a URL.
function getResponse
getResponse: ( handlers: Array<RequestHandler>, request: Request, resolutionContext?: ResponseResolutionContext) => Promise<Response | undefined>;Finds a response for the given request instance in the array of request handlers.
Parameter handlers
The array of request handlers.
Parameter request
The
Requestinstance.Parameter resolutionContext
Request resolution options.
Returns
{Response} A mocked response, if any.
function isCommonAssetRequest
isCommonAssetRequest: (request: Request) => boolean;Determines if the given request is a static asset request. Useful when deciding which unhandled requests to ignore. Despite being ignored, you can still intercept and mock static assets by creating request handlers for them.
Example 1
import { isCommonAssetRequest } from 'msw' import { HttpNetworkFrame } from 'msw/experimental'
await worker.start({ onUnhandledFrame({ frame, defaults }) { if (frame instanceof HttpNetworkFrame && !isCommonAssetRequest(frame.data.request)) { defaults.warn() } } })
function isPassthroughResponse
isPassthroughResponse: (response: Response) => boolean;Returns
trueif the given response was created bypassthrough().Example 1
const response = passthrough() isPassthroughResponse(response) // true
function matchRequestUrl
matchRequestUrl: (url: URL, pattern: Path, baseUrl?: string) => Match;Match the given URL against a path pattern.
function passthrough
passthrough: () => HttpResponse<any>;Performs the intercepted request as-is.
This stops request handler lookup so no other handlers can affect this request past this point. Unlike
bypass(), this will not trigger an additional request.Example 1
http.get('/resource', () => { return passthrough() })
See Also
Classes
class HttpHandler
class HttpHandler extends RequestHandler< HttpHandlerInfo, HttpRequestParsedResult, HttpRequestResolverExtras<any>> {}Request handler for HTTP requests. Provides request matching based on method and URL.
constructor
constructor( method: HttpHandlerMethod, predicate: HttpRequestPredicate<PathParams<string>>, resolver: ResponseResolver<HttpRequestResolverExtras<any>, any, any>, options?: RequestHandlerOptions);method extendResolverArgs
protected extendResolverArgs: (args: { request: Request; parsedResult: HttpRequestParsedResult;}) => { params: PathParams<string>; cookies: Record<string, string> };method log
log: (args: { request: Request; response: Response }) => Promise<void>;method parse
parse: (args: { request: Request; resolutionContext?: ResponseResolutionContext;}) => Promise<{ match: Match; cookies: Record<string, string> }>;method predicate
predicate: (args: { request: Request; parsedResult: HttpRequestParsedResult; resolutionContext?: ResponseResolutionContext;}) => Promise<boolean>;class HttpResponse
class HttpResponse<BodyType extends DefaultBodyType> extends FetchResponse {}A drop-in replacement for the standard
Responseclass to allow additional features, like mocking the responseSet-Cookieheader.Example 1
new HttpResponse('Hello world', { status: 201 }) HttpResponse.json({ name: 'John' }) HttpResponse.formData(form)
See Also
constructor
constructor(body?: DefaultBodyType, init?: HttpResponseInit);property [bodyType]
readonly [bodyType]: DefaultBodyType;method arrayBuffer
static arrayBuffer: <BodyType extends ArrayBuffer | SharedArrayBuffer>( body?: BodyType, init?: HttpResponseInit) => HttpResponse<BodyType>;Create a
Responsewith anArrayBufferbody.Example 1
const buffer = new ArrayBuffer(3) const view = new Uint8Array(buffer) view.set([1, 2, 3])
HttpResponse.arrayBuffer(buffer)
method error
static error: () => HttpResponse<any>;method formData
static formData: ( body?: FormData, init?: HttpResponseInit) => HttpResponse<FormData>;Create a
Responsewith aFormDatabody.Example 1
const data = new FormData() data.set('name', 'Alice')
HttpResponse.formData(data)
method html
static html: <BodyType extends string>( body?: BodyType | null, init?: HttpResponseInit) => HttpResponse<BodyType>;Create a
Responsewith aContent-Type: "text/html"body.Example 1
HttpResponse.html(
<p class="author">Jane Doe</p>) HttpResponse.html(<main id="abc-123">Main text</main>, { status: 201 })
method json
static json: <BodyType extends JsonBodyType>( body?: TransparentNoInfer<BodyType> | null | undefined, init?: HttpResponseInit) => HttpResponse<BodyType>;Create a
Responsewith aContent-Type: "application/json"body.Example 1
HttpResponse.json({ firstName: 'John' }) HttpResponse.json({ error: 'Not Authorized' }, { status: 401 })
method text
static text: <BodyType extends string>( body?: TransparentNoInfer<BodyType> | null, init?: HttpResponseInit) => HttpResponse<BodyType>;Create a
Responsewith aContent-Type: "text/plain"body.Example 1
HttpResponse.text('hello world') HttpResponse.text('Error', { status: 500 })
method xml
static xml: <BodyType extends string>( body?: BodyType | null, init?: HttpResponseInit) => HttpResponse<BodyType>;Create a
Responsewith aContent-Type: "application/xml"body.Example 1
HttpResponse.xml(
<user name="John" />) HttpResponse.xml(<article id="abc-123" />, { status: 201 })
class RequestHandler
abstract class RequestHandler< HandlerInfo extends RequestHandlerDefaultInfo = RequestHandlerDefaultInfo, ParsedResult extends Record<string, any> | undefined = any, ResolverExtras extends Record<string, unknown> = any, HandlerOptions extends RequestHandlerOptions = RequestHandlerOptions> extends Handler {}constructor
constructor(args: RequestHandlerArgs<HandlerInfo, HandlerOptions>);property cache
static cache: WeakMap< StrictRequest<DefaultBodyType>, StrictRequest<DefaultBodyType>>;property info
info: RequestHandlerDefaultInfo & RequestHandlerInternalInfo;property isUsed
isUsed: boolean;Indicates whether this request handler has been used (its resolver has successfully executed).
property kind
readonly kind: string;property resolver
protected resolver: ResponseResolver<ResolverExtras, any, any>;method extendResolverArgs
protected extendResolverArgs: (_args: { request: Request; parsedResult: ParsedResult;}) => ResolverExtras;method log
abstract log: (args: { request: Request; response: Response; parsedResult: ParsedResult;}) => void;Print out the successfully handled request.
method parse
parse: (_args: { request: Request; resolutionContext?: ResponseResolutionContext;}) => Promise<ParsedResult>;Parse the intercepted request to extract additional information from it. Parsed result is then exposed to other methods of this request handler.
method predicate
abstract predicate: (args: { request: Request; parsedResult: ParsedResult; resolutionContext?: ResponseResolutionContext;}) => boolean | Promise<boolean>;Determine if the intercepted request should be mocked.
method reset
reset: () => void;Reset the runtime state accumulated during response resolution, such as generator iterator progress. Called when this handler is removed from the active handlers list so re-adding it later starts from a clean state.
method restore
restore: () => void;Restore this handler so it can match requests again after being exhausted (e.g. via
{ once: true }). Also clears any accumulated resolution state.
method run
run: (args: { request: StrictRequest<any>; requestId: string; resolutionContext?: ResponseResolutionContext;}) => Promise<RequestHandlerExecutionResult<ParsedResult> | null>;Execute this request handler and produce a mocked response using the given resolver function.
method test
test: (args: { request: Request; resolutionContext?: ResponseResolutionContext;}) => Promise<boolean>;Test if this handler matches the given request.
This method is not used internally but is exposed as a convenience method for consumers writing custom handlers.
class WebSocketConnectionEvent
class WebSocketConnectionEvent<Message = WebSocketData> extends TypedEvent<void, void, 'connection'> implements WebSocketHandlerConnection<Message> {}constructor
constructor(connection: WebSocketHandlerConnection<Message>);property client
readonly client: WebSocketClientHandle<Message>;property info
readonly info: WebSocketConnectionInfo;property params
readonly params: PathParams<string>;property server
readonly server: WebSocketServerHandle<Message>;class WebSocketHandler
class WebSocketHandler< Extension extends AnyWebSocketExtension = WebSocketExtension> extends Handler {}constructor
constructor(url: Path, options?: WebSocketHandlerOptions);property [kEmitter]
protected [kEmitter]: Emitter<WebSocketHandlerEventMap<Extension>>;property callFrame
callFrame?: string;property extensions
protected readonly extensions: readonly WebSocketExtension<unknown, unknown>[];property id
id: string;property kind
readonly kind: string;property url
protected readonly url: Path;method [kConnect]
protected [kConnect]: ( connection: WebSocketHandlerResolvedConnection<Extension>) => boolean;method log
log: (connection: WebSocketConnectionEventData) => () => void;method parse
parse: (args: { url: string | URL; resolutionContext?: WebSocketResolutionContext;}) => WebSocketHandlerParsedResult;method predicate
predicate: (args: { url: string | URL; parsedResult: WebSocketHandlerParsedResult;}) => boolean;method run
run: ( connection: WebSocketConnectionEventData, resolutionContext?: WebSocketResolutionContext) => Promise<WebSocketHandlerResolvedConnection<Extension> | null>;method test
test: ( url: string | URL, resolutionContext?: WebSocketResolutionContext & { strict?: boolean }) => boolean;Interfaces
interface HttpHandlerInfo
interface HttpHandlerInfo extends RequestHandlerDefaultInfo {}interface HttpResponseInit
interface HttpResponseInit extends ResponseInit {}property type
type?: ResponseType;interface Match
interface Match {}interface RequestHandlerOptions
interface RequestHandlerOptions {}property once
once?: boolean;interface ResponseResolutionContext
interface ResponseResolutionContext {}interface SharedOptions
interface SharedOptions {}property onUnhandledFrame
onUnhandledFrame?: UnhandledFrameHandle;Specifies how to react to a network frame (e.g. a request or a WebSocket connection) that has no corresponding handler. Warns on unhandled frames by default.
Example 1
worker.start({ onUnhandledFrame: 'bypass' })
Example 2
worker.start({ onUnhandledFrame: 'warn' })
Example 3
server.listen({ onUnhandledFrame: 'error' })
Example 4
server.listen({ onUnhandledFrame({ frame, defaults }) { defaults.warn() } })
interface StrictRequest
interface StrictRequest<BodyType extends JsonBodyType> extends Request {}interface WebSocketHandlerConnection
interface WebSocketHandlerConnection<Message = WebSocketData> {}The connection matched by a handler.
Typed against the connection handles, not the connection classes, so a handler accepts connections living anywhere (e.g. in another runtime, or a custom implementation of the handles).
interface WebSocketHandlerOptions
interface WebSocketHandlerOptions {}property extensions
extensions?: ReadonlyArray<AnyWebSocketExtension>;WebSocket extensions applied to every connection matched by this handler, left to right. The last one applied encodes and decodes the traffic, and every one of them extends the connection event with its own API.
interface WebSocketLinkOptions
interface WebSocketLinkOptions<Extensions extends WebSocketExtensions = []> {}property extensions
extensions?: Extensions;Extensions applied to every connection intercepted by this link, left to right. Encoding and decoding happen behind the scenes:
client.send(),server.send(),broadcast(), and themessageevents all operate on the extensions' messages, and each extension's own API is exposed on the connection event.Example 1
const chat = ws.link('wss://chat.example.com', { extensions: [new SocketIo()] }) chat.addEventListener('connection', ({ client, rooms }) => { client.send({ event: 'greeting', args: ['hello'] }) })
Enums
enum HttpMethods
enum HttpMethods { HEAD = 'HEAD', GET = 'GET', POST = 'POST', PUT = 'PUT', PATCH = 'PATCH', OPTIONS = 'OPTIONS', DELETE = 'DELETE',}Type Aliases
type AnyHandler
type AnyHandler = RequestHandler | WebSocketHandler<AnyWebSocketExtension>;type AsyncResponseResolverReturnType
type AsyncResponseResolverReturnType<ResponseBodyType extends DefaultBodyType> = MaybePromise< | ResponseResolverReturnType<ResponseBodyType> | Iterable< MaybeAsyncResponseResolverReturnType<ResponseBodyType>, MaybeAsyncResponseResolverReturnType<ResponseBodyType>, MaybeAsyncResponseResolverReturnType<ResponseBodyType> > | AsyncIterable< MaybeAsyncResponseResolverReturnType<ResponseBodyType>, MaybeAsyncResponseResolverReturnType<ResponseBodyType>, MaybeAsyncResponseResolverReturnType<ResponseBodyType> > >;type DefaultBodyType
type DefaultBodyType = | Record<string, any> | DefaultRequestMultipartBody | string | number | boolean | null | undefined;type DefaultRequestMultipartBody
type DefaultRequestMultipartBody = Record< string, string | File | Array<string | File>>;type DelayMode
type DelayMode = 'real' | 'infinite';type HttpCustomPredicate
type HttpCustomPredicate<Params extends PathParams> = (args: { request: Request; cookies: Record<string, string>;}) => HttpCustomPredicateResult<Params> | Promise<HttpCustomPredicateResult<Params>>;type HttpHandlerMethod
type HttpHandlerMethod = string | RegExp;type HttpRequestHandler
type HttpRequestHandler = < Params extends PathParams<keyof Params> = PathParams, RequestBodyType extends DefaultBodyType = DefaultBodyType, ResponseBodyType extends DefaultBodyType = undefined>( predicate: HttpRequestPredicate<Params>, resolver: HttpResponseResolver<Params, RequestBodyType, ResponseBodyType>, options?: RequestHandlerOptions) => HttpHandler;type HttpRequestParsedResult
type HttpRequestParsedResult = { match: Match; cookies: Record<string, string>;};type HttpRequestResolverExtras
type HttpRequestResolverExtras<Params extends PathParams> = { params: Params; cookies: Record<string, string>;};type HttpResponseResolver
type HttpResponseResolver< Params extends PathParams<keyof Params> = PathParams, RequestBodyType extends DefaultBodyType = DefaultBodyType, ResponseBodyType extends DefaultBodyType = DefaultBodyType> = ResponseResolver< HttpRequestResolverExtras<Params>, RequestBodyType, ResponseBodyType>;type JsonBodyType
type JsonBodyType = | Record<string, any> | string | number | boolean | null | undefined;type Path
type Path = string | RegExp;type PathParams
type PathParams<KeyType extends keyof any = string> = { [ParamName in KeyType]?: string | ReadonlyArray<string>;};type RequestQuery
type RequestQuery = { [queryName: string]: string;};type ResponseResolver
type ResponseResolver< ResolverExtraInfo extends Record<string, unknown> = Record<string, unknown>, RequestBodyType extends DefaultBodyType = DefaultBodyType, ResponseBodyType extends DefaultBodyType = undefined> = ( info: ResponseResolverInfo<ResolverExtraInfo, RequestBodyType>) => AsyncResponseResolverReturnType<ResponseBodyType>;type ResponseResolverInfo
type ResponseResolverInfo< ResolverExtraInfo extends Record<string, unknown>, RequestBodyType extends DefaultBodyType = DefaultBodyType> = { request: StrictRequest<RequestBodyType>; requestId: string; /** * Schedule a callback to run after this response resolver completes. * Handy for cleaning up the side effects introduced in the resolver. * * For responses with a `ReadableStream` body (including `sse()` handlers), * the callback runs once the response stream settles: it is read to * completion, errored, or canceled, or the request is aborted. * @example * sse('/', ({ client, finalize }) => { * const interval = setInterval(() => client.send({ data: 'ping' })) * finalize(() => clearInterval(interval)) * }) */ finalize: ResponseResolverFinalizeFunction;} & ResolverExtraInfo;type ResponseResolverReturnType
type ResponseResolverReturnType< ResponseBodyType extends DefaultBodyType = undefined> = | ([ResponseBodyType] extends [undefined] ? Response : ResponseBodyType extends Record<string, any> | undefined ? HttpResponse<ResponseBodyType> | DefaultUnsafeFetchResponse : HttpResponse<ResponseBodyType>) | undefined | void;type ServerSentEventMessage
type ServerSentEventMessage< EventMap extends EventMapConstraint = { message: unknown; }> = | ToEventDiscriminatedUnion< EventMap & { message: unknown; } > | { id?: never; event?: never; data?: never; retry: number; };type ServerSentEventRequestHandler
type ServerSentEventRequestHandler = < EventMap extends EventMapConstraint = { message: unknown; }, Params extends PathParams<keyof Params> = PathParams, RequestPath extends Path = Path>( path: RequestPath, resolver: ServerSentEventResolver<EventMap, Params>) => HttpHandler;type ServerSentEventResolver
type ServerSentEventResolver< EventMap extends EventMapConstraint, Params extends PathParams> = ResponseResolver<ServerSentEventResolverExtras<EventMap, Params>, any, any>;type ServerSentEventResolverExtras
type ServerSentEventResolverExtras< EventMap extends EventMapConstraint, Params extends PathParams> = HttpRequestResolverExtras<Params> & { client: ServerSentEventClient<EventMap>; server: ServerSentEventServer;};type UnhandledFrameHandle
type UnhandledFrameHandle = UnhandledFrameStrategy | UnhandledFrameCallback;type UnhandledFrameStrategy
type UnhandledFrameStrategy = 'bypass' | 'warn' | 'error';type WebSocketEventListener
type WebSocketEventListener< EventType extends keyof WebSocketHandlerEventMap, Extension extends AnyWebSocketExtension = WebSocketExtension> = EventMap.Listener<WebSocketHandlerEventMap<Extension>, EventType>;type WebSocketHandlerEventMap
type WebSocketHandlerEventMap< Extension extends AnyWebSocketExtension = WebSocketExtension> = { connection: WebSocketHandlerConnectionEvent<Extension>;};type WebSocketLink
type WebSocketLink<Extension extends AnyWebSocketExtension = WebSocketExtension> = { /** * A set of all WebSocket clients connected * to this link. * * @see {@link https://mswjs.io/docs/api/ws#clients `clients` API reference} */ clients: Set<WebSocketClientHandle<WebSocketExtensionMessage<Extension>>>; /** * Adds an event listener to this WebSocket link. * * @example * const chat = ws.link('wss://chat.example.com') * chat.addEventListener('connection', listener) * * @see {@link https://mswjs.io/docs/api/ws#onevent-listener `on()` API reference} */ addEventListener: <EventType extends keyof WebSocketHandlerEventMap>( event: EventType, listener: WebSocketEventListener<EventType, Extension> ) => WebSocketHandler<Extension>; /** * Broadcasts the given data to all WebSocket clients. * * @example * const service = ws.link('wss://example.com') * service.addEventListener('connection', () => { * service.broadcast('hello, everyone!') * }) * * @see {@link https://mswjs.io/docs/api/ws#broadcastdata `broadcast()` API reference} */ broadcast: (data: WebSocketExtensionMessage<Extension>) => void; /** * Broadcasts the given data to all WebSocket clients * except the ones provided in the `clients` argument. * * @example * const service = ws.link('wss://example.com') * service.addEventListener('connection', ({ client }) => { * service.broadcastExcept(client, 'hi, the rest of you!') * }) * * @see {@link https://mswjs.io/docs/api/ws#broadcastexceptclients-data `broadcast()` API reference} */ broadcastExcept: ( clients: | WebSocketClientHandle<WebSocketExtensionMessage<Extension>> | Array<WebSocketClientHandle<WebSocketExtensionMessage<Extension>>>, data: WebSocketExtensionMessage<Extension> ) => void;};Namespaces
namespace virtual:msw
module 'virtual:msw' {}variable network
const network: Omit<NetworkApi<NetworkSource<any>[]>, 'enable' | 'disable'> & { enable(): void | Promise<void>; disable(): void | Promise<void>;};namespace virtual:msw/options
module 'virtual:msw/options' {}variable defaultNetworkOptions
const defaultNetworkOptions: any;Package Files (17)
- lib/_chunks/handlers-controller.d.ts
- lib/_chunks/http-handler.d.ts
- lib/_chunks/http.d.ts
- lib/_chunks/match-request-url.d.ts
- lib/_chunks/request-handler.d.ts
- lib/_chunks/shared-options.d.ts
- lib/_chunks/sse.d.ts
- lib/_chunks/ws.d.ts
- lib/core/index.d.ts
- lib/utils/bypass.d.ts
- lib/utils/delay.d.ts
- lib/utils/get-clean-url-string.d.ts
- lib/utils/get-response.d.ts
- lib/utils/is-common-asset-request.d.ts
- lib/utils/passthrough.d.ts
- src/vite/client.d.ts
- src/vite/options.d.ts
Dependencies (12)
Dev Dependencies (42)
- @commitlint/cli
- @commitlint/config-conventional
- @epic-web/test-server
- @fastify/websocket
- @graphql-typed-document-node/core
- @ossjs/release
- @playwright/test
- @types/express
- @types/json-bigint
- @types/node
- @types/serviceworker
- @types/ws
- @vitest/browser-playwright
- @web/dev-server
- axios
- commitizen
- cross-env
- cz-conventional-changelog
- esbuild
- express
- fastify
- fs-teardown
- glob
- graphql
- graphql-ws
- graphql-yoga
- jsdom
- json-bigint
- knip
- lint-staged
- msw
- oxlint
- page-with
- prettier
- publint
- rimraf
- simple-git-hooks
- tsdown
- typescript
- vite
- vitest
- ws
Peer Dependencies (3)
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/msw.
- Markdown[](https://www.jsdocs.io/package/msw)
- HTML<a href="https://www.jsdocs.io/package/msw"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 6399 ms. - Missing or incorrect documentation? Open an issue for this package.
