msw-request-assertions weekly downloads statistics

MSW Request Assertions

A powerful testing library that provides custom assertion matchers for Mock Service Worker (MSW). Test your API interactions with confidence by asserting on request properties like headers, body, query parameters, and more.

Features | Installation | Migration | API | Contributing

[!IMPORTANT] Before using this library, please read MSW's official guidance on avoiding request assertions. The MSW team recommends testing how your application reacts to requests rather than asserting on request details. This library should primarily be used for edge cases, like request details have no observable application behavior.

✨ Features

• ✅ Assert on any aspect of HTTP and GraphQL requests • ✅ Works with Vitest and Jest

📦 Installation

🚀 Quick Start

Setup for Vitest

msw-request-assertions/vitest ships Vitest 5 matcher types (Matchers).

Vitest 4: use msw-request-assertions/vitest/v4 instead. See Migration.

Setup for Jest

[!NOTE] Jest support is not a first-class citizen due to complex setup requirements between ESM and CJS modules. While we provide Jest compatibility, our main development and testing efforts are focused on Vitest. Feel free to raise an issue if you encounter Jest-specific problems.

Basic Example

🔄 Migration

Vitest 5 matcher types (breaking)

Default msw-request-assertions/vitest types now match Vitest 5:

Vitest 4's Matchers is a different type-parameter list. TypeScript cannot merge both in one declaration (TS2428).

Vitest 5: keep the existing import. No code change.

Vitest 4: switch the setup import and tsconfig types entry to /vitest/v4. Runtime is the same.

Do not import both /vitest and /vitest/v4 in the same TypeScript project.

💻 API

• Basic Request Matchers • toHaveBeenRequested • toHaveBeenRequestedTimes • Body Matchers • toHaveBeenRequestedWithBody • toHaveBeenRequestedWithJsonBody • Header Matchers • toHaveBeenRequestedWithHeaders • URL Matchers • toHaveBeenRequestedWithQueryString • toHaveBeenRequestedWithHash • toHaveBeenRequestedWithPathParameters • GraphQL Matchers • toHaveBeenRequestedWithGqlQuery • toHaveBeenRequestedWithGqlVariables • Unified Matcher • toHaveBeenRequestedWith • Nth Call Matchers • Types • RequestPayload

Basic Request Matchers

toHaveBeenRequested

Assert that a handler was called at least once.

toHaveBeenRequestedTimes

Assert that a handler was called exactly n times.

Body Matchers

toHaveBeenRequestedWithBody

Assert on raw request body (string).

toHaveBeenRequestedWithJsonBody

Assert on JSON request body (parsed object).

Header Matchers

toHaveBeenRequestedWithHeaders

Assert on request headers. Headers are case-insensitive.

URL Matchers

toHaveBeenRequestedWithQueryString

Assert on URL query parameters.

[!NOTE] The input is a string to avoid serialization issues, especially with arrays and custom formats. This gives you full control over the exact query string format.

toHaveBeenRequestedWithHash

Assert on URL hash fragment.

toHaveBeenRequestedWithPathParameters

Assert on URL path parameters (for dynamic routes).

GraphQL Matchers

toHaveBeenRequestedWithGqlQuery

Assert on GraphQL query string.

toHaveBeenRequestedWithGqlVariables

Assert on GraphQL variables.

Unified Matcher

toHaveBeenRequestedWith

Assert on multiple request properties at once. See RequestPayload for all available properties.

Nth Call Matchers

All matchers have an "nth" variant to assert on specific call positions. The first argument is the call number (1-indexed).

Types

RequestPayload

The payload object used with toHaveBeenRequestedWith matcher.

🤝 Contributing

Development

Local Development

Build

Release

This repo uses Release Please to release.

To release a new version

1. Merge your changes into the main branch. 2. An automated GitHub Action will run, triggering the creation of a Release PR. 3. Merge the release PR. 4. Wait for the second GitHub Action to run automatically. 5. Congratulations, you're all set!

Description from the npm listing.