msw

Version 2.7.0
Published 1 month ago
4.47 MB
18 dependencies
MIT license

Install

npm i msw

yarn add msw

pnpm add msw

Overview

Seamless REST/GraphQL API mocking library for browser and Node.js.

Index

Variables

variable graphql

const graphql: {
    link: typeof createGraphQLLink;
    query: GraphQLRequestHandler;
    mutation: GraphQLRequestHandler;
    operation: <
        Query extends GraphQLQuery = GraphQLQuery,
        Variables extends GraphQLVariables = GraphQLVariables
    >(
        resolver: ResponseResolver<
            GraphQLResolverExtras<Variables>,
            null,
            { data?: Query; errors?: readonly GraphQLError[] }
        >
    ) => GraphQLHandler;
};

A namespace to intercept and mock GraphQL operations
Example 1
graphql.query('GetUser', resolver) graphql.mutation('DeletePost', resolver)
See Also

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 MAX_SERVER_RESPONSE_TIME

const MAX_SERVER_RESPONSE_TIME: number;

variable MIN_SERVER_RESPONSE_TIME

const MIN_SERVER_RESPONSE_TIME: number;

variable NODE_SERVER_RESPONSE_TIME

const NODE_SERVER_RESPONSE_TIME: number;

variable SET_TIMEOUT_MAX_ALLOWED_INT

const SET_TIMEOUT_MAX_ALLOWED_INT: number;

variable ws

const ws: { link: typeof createWebSocketLinkHandler };

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 Request instance 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 cleanUrl

cleanUrl: (path: string) => string;

Removes search parameters and the fragment from a given URL string.

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 getResponse

getResponse: (
    handlers: Array<RequestHandler>,
    request: Request
) => 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 Request instance.
Returns
{Response} A mocked response, if any.

function handleRequest

handleRequest: (
    request: Request,
    requestId: string,
    handlers: Array<RequestHandler>,
    options: RequiredDeep<SharedOptions>,
    emitter: Emitter<LifeCycleEventsMap>,
    handleRequestOptions?: HandleRequestOptions
) => Promise<Response | undefined>;

function matchRequestUrl

matchRequestUrl: (url: URL, path: Path, baseUrl?: string) => Match;

Returns the result of matching given request URL against a mask.

function passthrough

passthrough: () => StrictResponse<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 GraphQLHandler

class GraphQLHandler extends RequestHandler<
    GraphQLHandlerInfo,
    GraphQLRequestParsedResult,
    GraphQLResolverExtras<any>
> {}

constructor

constructor(
    operationType: any,
    operationName: any,
    endpoint: Path,
    resolver: ResponseResolver<GraphQLResolverExtras<any>, any, any>,
    options?: RequestHandlerOptions
);

property parsedRequestCache

static parsedRequestCache: WeakMap<
    Request,
    ParsedGraphQLQuery & { query: string; variables?: GraphQLVariables }
>;

method extendResolverArgs

protected extendResolverArgs: (args: {
    request: Request;
    parsedResult: GraphQLRequestParsedResult;
}) => {
    query: string;
    operationName: string;
    variables: GraphQLVariables;
    cookies: Record<string, string>;
};

method log

log: (args: {
    request: Request;
    response: Response;
    parsedResult: GraphQLRequestParsedResult;
}) => Promise<void>;

method parse

parse: (args: { request: Request }) => Promise<GraphQLRequestParsedResult>;

method parseGraphQLRequestOrGetFromCache

parseGraphQLRequestOrGetFromCache: (
    request: Request
) => Promise<ParsedGraphQLRequest<GraphQLVariables>>;

Parses the request body, once per request, cached across all GraphQL handlers. This is done to avoid multiple parsing of the request body, which each requires a clone of the request.

method predicate

predicate: (args: {
    request: Request;
    parsedResult: GraphQLRequestParsedResult;
}) => boolean;

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,
    path: Path,
    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;
}) => boolean;

class HttpResponse

class HttpResponse extends Response {}

A drop-in replacement for the standard Response class to allow additional features, like mocking the response Set-Cookie header.
Example 1
new HttpResponse('Hello world', { status: 201 }) HttpResponse.json({ name: 'John' }) HttpResponse.formData(form)
See Also

constructor

constructor(body?: BodyInit, init?: HttpResponseInit);

method arrayBuffer

static arrayBuffer: (
    body?: ArrayBuffer | SharedArrayBuffer,
    init?: HttpResponseInit
) => Response;

Create a Response with an ArrayBuffer body.
Example 1
const buffer = new ArrayBuffer(3) const view = new Uint8Array(buffer) view.set([1, 2, 3])
HttpResponse.arrayBuffer(buffer)

method formData

static formData: (body?: FormData, init?: HttpResponseInit) => Response;

Create a Response with a FormData body.
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
) => Response;

Create a Response with a Content-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?: NoInfer<BodyType> | null,
    init?: HttpResponseInit
) => StrictResponse<BodyType>;

Create a Response with a Content-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?: NoInfer<BodyType> | null,
    init?: HttpResponseInit
) => StrictResponse<BodyType>;

Create a Response with a Content-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
) => Response;

Create a Response with a Content-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
> {}

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 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;

Determine if the intercepted request should be mocked.

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 SetupApi

abstract class SetupApi<EventsMap extends EventMap> extends Disposable {}

Generic class for the mock API setup.

constructor

constructor(
    ...initialHandlers: (
        | RequestHandler<
              RequestHandlerDefaultInfo,
              any,
              any,
              RequestHandlerOptions
          >
        | WebSocketHandler
    )[]
);

property emitter

protected readonly emitter: Emitter<EventsMap>;

property events

readonly events: LifeCycleEventEmitter<EventsMap>;

property handlersController

protected handlersController: HandlersController;

property publicEmitter

protected readonly publicEmitter: Emitter<EventsMap>;

method listHandlers

listHandlers: () => ReadonlyArray<RequestHandler | WebSocketHandler>;

method resetHandlers

resetHandlers: (
    ...nextHandlers: Array<RequestHandler | WebSocketHandler>
) => void;

method restoreHandlers

restoreHandlers: () => void;

method use

use: (...runtimeHandlers: Array<RequestHandler | WebSocketHandler>) => void;

class WebSocketHandler

class WebSocketHandler {}

constructor

constructor(url: Path);

property [kEmitter]

protected [kEmitter]: Emitter<WebSocketHandlerEventMap>;

property callFrame

callFrame?: string;

property id

id: string;

method [kDispatchEvent]

[kDispatchEvent]: (
    event: MessageEvent<WebSocketConnectionData>
) => Promise<void>;

method parse

parse: (args: {
    event: MessageEvent<WebSocketConnectionData>;
}) => WebSocketHandlerParsedResult;

method predicate

predicate: (args: {
    event: MessageEvent<WebSocketConnectionData>;
    parsedResult: WebSocketHandlerParsedResult;
}) => boolean;

Interfaces

interface GraphQLJsonRequestBody

interface GraphQLJsonRequestBody<Variables extends GraphQLVariables> {}

property query

query: string;

property variables

variables?: Variables;

interface HandleRequestOptions

interface HandleRequestOptions {}

property resolutionContext

resolutionContext?: {
    /**
     * A base url to use when resolving relative urls.
     * @note This is primarily used by the `@mswjs/http-middleware`
     * to resolve relative urls in the context of the running server
     */
    baseUrl?: string;
};

resolutionContext is not part of the general public api but is exposed to aid in creating extensions like @mswjs/http-middleware.

method onMockedResponse

onMockedResponse: (
    response: Response,
    handler: RequiredDeep<HandlersExecutionResult>
) => void;

Invoked when the mocked response is ready to be sent.

method onPassthroughResponse

onPassthroughResponse: (request: Request) => void;

Invoked whenever a request is performed as-is.

interface HttpResponseInit

interface HttpResponseInit extends ResponseInit {}

property type

type?: ResponseType;

interface Match

interface Match {}

property matches

matches: boolean;

property params

params?: PathParams;

interface RequestHandlerOptions

interface RequestHandlerOptions {}

property once

once?: boolean;

interface SharedOptions

interface SharedOptions {}

property onUnhandledRequest

onUnhandledRequest?: UnhandledRequestStrategy;

Specifies how to react to a request that has no corresponding request handler. Warns on unhandled requests by default.
Example 1
worker.start({ onUnhandledRequest: 'bypass' })
Example 2
worker.start({ onUnhandledRequest: 'warn' })
Example 3
server.listen({ onUnhandledRequest: 'error' })

interface StrictRequest

interface StrictRequest<BodyType extends DefaultBodyType> extends Request {}

method json

json: () => Promise<BodyType>;

interface StrictResponse

interface StrictResponse<BodyType extends DefaultBodyType> extends Response {}

Opaque Response type that supports strict body type.

property [bodyType]

readonly [bodyType]: BodyType;

interface WebSocketHandlerConnection

interface WebSocketHandlerConnection extends WebSocketConnectionData {}

property params

params: PathParams;

Enums

enum HttpMethods

enum HttpMethods {
    HEAD = 'HEAD',
    GET = 'GET',
    POST = 'POST',
    PUT = 'PUT',
    PATCH = 'PATCH',
    OPTIONS = 'OPTIONS',
    DELETE = 'DELETE',
}

member DELETE

DELETE = 'DELETE'

member GET

GET = 'GET'

member HEAD

HEAD = 'HEAD'

member OPTIONS

OPTIONS = 'OPTIONS'

member PATCH

PATCH = 'PATCH'

member POST

POST = 'POST'

member PUT

PUT = 'PUT'

Type Aliases

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 GraphQLQuery

type GraphQLQuery = Record<string, any>;

type GraphQLRequestBody

type GraphQLRequestBody<VariablesType extends GraphQLVariables> =
    | GraphQLJsonRequestBody<VariablesType>
    | GraphQLMultipartRequestBody
    | Record<string, any>
    | undefined;

type GraphQLRequestHandler

type GraphQLRequestHandler = <
    Query extends GraphQLQuery = GraphQLQuery,
    Variables extends GraphQLVariables = GraphQLVariables
>(
    operationName:
        | GraphQLHandlerNameSelector
        | DocumentNode
        | TypedDocumentNode<Query, Variables>,
    resolver: GraphQLResponseResolver<
        [Query] extends [never] ? GraphQLQuery : Query,
        Variables
    >,
    options?: RequestHandlerOptions
) => GraphQLHandler;

type GraphQLResponseResolver

type GraphQLResponseResolver<
    Query extends GraphQLQuery = GraphQLQuery,
    Variables extends GraphQLVariables = GraphQLVariables
> = ResponseResolver<
    GraphQLResolverExtras<Variables>,
    null,
    GraphQLResponseBody<[Query] extends [never] ? GraphQLQuery : Query>
>;

type GraphQLVariables

type GraphQLVariables = Record<string, any>;

type HttpRequestHandler

type HttpRequestHandler = <
    Params extends PathParams<keyof Params> = PathParams,
    RequestBodyType extends DefaultBodyType = DefaultBodyType,
    ResponseBodyType extends DefaultBodyType = undefined,
    RequestPath extends Path = Path
>(
    path: RequestPath,
    resolver: HttpResponseResolver<Params, RequestBodyType, ResponseBodyType>,
    options?: RequestHandlerOptions
) => HttpHandler;

type HttpRequestParsedResult

type HttpRequestParsedResult = {
    match: Match;
    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 LifeCycleEventsMap

type LifeCycleEventsMap = {
    'request:start': [
        args: {
            request: Request;
            requestId: string;
        }
    ];
    'request:match': [
        args: {
            request: Request;
            requestId: string;
        }
    ];
    'request:unhandled': [
        args: {
            request: Request;
            requestId: string;
        }
    ];
    'request:end': [
        args: {
            request: Request;
            requestId: string;
        }
    ];
    'response:mocked': [
        args: {
            response: Response;
            request: Request;
            requestId: string;
        }
    ];
    'response:bypass': [
        args: {
            response: Response;
            request: Request;
            requestId: string;
        }
    ];
    unhandledException: [
        args: {
            error: Error;
            request: Request;
            requestId: string;
        }
    ];
};

type ParsedGraphQLRequest

type ParsedGraphQLRequest<
    VariablesType extends GraphQLVariables = GraphQLVariables
> =
    | (ParsedGraphQLQuery & {
          query: string;
          variables?: VariablesType;
      })
    | 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 ResponseResolverReturnType

type ResponseResolverReturnType<
    ResponseBodyType extends DefaultBodyType = undefined
> =
    | ([ResponseBodyType] extends [undefined]
          ? Response
          : StrictResponse<ResponseBodyType>)
    | undefined
    | void;

type WebSocketEventListener

type WebSocketEventListener<EventType extends keyof WebSocketHandlerEventMap> = (
    ...args: WebSocketHandlerEventMap[EventType]
) => void;

type WebSocketHandlerEventMap

type WebSocketHandlerEventMap = {
    connection: [args: WebSocketHandlerConnection];
};

type WebSocketLink

type WebSocketLink = {
    /**
     * A set of all WebSocket clients connected
     * to this link.
     *
     * @see {@link https://mswjs.io/docs/api/ws#clients `clients` API reference}
     */
    clients: Set<WebSocketClientConnectionProtocol>;
    /**
     * 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>
    ): WebSocketHandler;
    /**
     * 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: WebSocketData): 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:
            | WebSocketClientConnectionProtocol
            | Array<WebSocketClientConnectionProtocol>,
        data: WebSocketData
    ): void;
};

Package Files (17)

Dependencies (18)

Peer Dependencies (1)

typescript

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

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](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 1 month ago.
Package analyzed in 6111 ms.
Missing or incorrect documentation? Open an issue for this package.

msw

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Variables

variable graphql

Example 1

See Also

variable http

Example 1

See Also

variable MAX_SERVER_RESPONSE_TIME

variable MIN_SERVER_RESPONSE_TIME

variable NODE_SERVER_RESPONSE_TIME

variable SET_TIMEOUT_MAX_ALLOWED_INT

variable ws

Example 1

See Also

Functions

function bypass

Example 1

See Also

function cleanUrl

function delay

Example 1

See Also

function getResponse

Parameter handlers

Parameter request

Returns

function handleRequest

function matchRequestUrl

function passthrough

Example 1

See Also

Classes

class GraphQLHandler

constructor

property parsedRequestCache

method extendResolverArgs

method log

method parse

method parseGraphQLRequestOrGetFromCache

method predicate

class HttpHandler

constructor

method extendResolverArgs

method log

method parse

method predicate

class HttpResponse

Example 1

See Also

constructor

method arrayBuffer

Example 1

method formData

Example 1

method html

Example 1

method json

Example 1

method text

Example 1

method xml

Example 1

class RequestHandler

constructor

property cache

property info

property isUsed

property resolver

method extendResolverArgs

method log