@scenarist/msw-adapter

⚠️ INTERNAL PACKAGE - DO NOT INSTALL DIRECTLY

This package is an internal implementation detail of Scenarist and is NOT published to npm. It exists as a workspace dependency used by framework adapters.

Why is this package private?

You should install a framework adapter instead:

- ✅ @scenarist/express-adapter - For Express applications
- ✅ @scenarist/nextjs-adapter - For Next.js applications
- ✅ @scenarist/core - For building custom adapters

This package is private because:

1. Not user-facing - Users never import from @scenarist/msw-adapter directly
2. Implementation detail - Provides MSW integration layer used internally by framework adapters
3. Prevents confusion - Publishing would mislead users into thinking they should install it
4. Version coupling - Framework adapters control which msw-adapter version they use
5. Simpler maintenance - Internal packages don't need semver/breaking change coordination
6. Cleaner API surface - Framework adapters ARE the public API, msw-adapter is hidden complexity

Dependency structure:

``
Your App
├─ @scenarist/express-adapter (public, install this!)
│ └─ @scenarist/msw-adapter (private, workspace:*)
│ └─ @scenarist/core (public)
│
└─ @scenarist/nextjs-adapter (public, install this!)
└─ @scenarist/msw-adapter (private, workspace:*)
└─ @scenarist/core (public)
`

---

What is Scenarist?

Scenarist enables concurrent tests to run with different backend states by switching mock scenarios at runtime via test IDs. Your real application code executes while external API responses are controlled by scenarios. This package provides the MSW integration layer that makes it all work.

The big picture:

`
Your App → Scenarist Adapter (Express/Next.js) → MSW Adapter → MSW → Intercepted HTTP
`

What this package does:

Converts Scenarist's serializable ScenaristMock data into MSW HttpHandler instances at runtime, enabling Scenarist to work with any Node.js framework.

Status: ✅ Stable - Used internally by all Scenarist framework adapters

---

For Framework Adapter Developers

If you're building a custom framework adapter for Scenarist, this package provides the MSW integration you need. Otherwise, you should use one of the existing public adapters listed above.

What does this package provide?

The MSW adapter is the bridge between Scenarist's serializable mock definitions and MSW's HTTP interception. It provides:

1. URL Matching - Converts URL patterns (with wildcards and path params) into MSW-compatible matchers
2. Mock Matching - Finds the right mock definition for incoming requests (with request content matching)
3. Response Building - Transforms ScenaristMock into MSW HttpResponse
4. Dynamic Handler - Creates a single MSW handler that routes based on active scenarios

Core Capabilities

This adapter implements all 25 Scenarist capabilities:

$3

- Body matching (partial match) - Match on request body fields
- Header matching (exact, case-insensitive) - Match on header values
- Query matching (exact) - Match on query parameters
- Combined matching - Combine body + headers + query
- Specificity-based selection - Most specific mock wins
- Fallback mocks - Mocks without criteria act as catch-all

$3

- Single responses - Return same response every time
- Response sequences - Ordered responses for polling scenarios
- Repeat modes - last, cycle, none behaviors
- Sequence exhaustion - Skip exhausted sequences to fallback

$3

- State capture - Extract values from requests
- State injection - Inject state into responses via templates
- Array append - Syntax: stateKey[] for arrays
- Nested paths - Dot notation: user.profile.name
- State isolation - Per test ID isolation
- State reset - Fresh state on scenario switch

$3

- Exact matches - https://api.example.com/users
- Wildcards - /api/, https://*/users
- Path parameters - /users/:id, /posts/:postId/comments/:commentId
- Native RegExp - /\/api\/v\d+\//, /\/users\/\d+$/ (weak comparison per MSW behavior)

$3

- Dynamic handler generation - Single handler routes at runtime
- Response building - Status codes, JSON bodies, headers, delays
- Automatic default fallback - Collects default + active scenario mocks together
- Strict mode - Fail on unmocked requests
- Test ID isolation - Separate state per test ID
- Framework-agnostic - Works with any Node.js framework

Features

- ✅ URL pattern matching - Exact matches, glob patterns (/api/), path parameters (/users/:id)
- ✅ Request content matching - Body, headers, query with specificity-based selection
- ✅ Dynamic MSW handler generation - Single handler routes to correct scenario at runtime
- ✅ Response building - Status codes, JSON bodies, headers, delays, state injection
- ✅ Sequences and state - Polling scenarios and stateful mocks fully supported
- ✅ Automatic default fallback - Collects default + active scenario mocks, uses specificity to select best match
- ✅ Framework-agnostic - Works with Express, Next.js, and any Node.js framework via HTTP-level interception

Internal Package

⚠️ This is an internal package used by framework adapters.

You typically don't install or use this directly. Instead, use a framework-specific adapter:

- @scenarist/express-adapter - For Express applications
- @scenarist/nextjs-adapter - For Next.js applications (App Router + Pages Router)

How It Works

$3

Converts string patterns into MSW-compatible URL matchers:

`typescript
import { matchesUrl } from "@scenarist/msw-adapter";

matchesUrl(
"https://api.github.com/users/octocat",
"GET",
"https://api.github.com/users/:username",
);
// Returns: { matches: true, params: { username: 'octocat' } }

matchesUrl("https://api.stripe.com/v1/charges", "POST", "*/v1/charges");
// Returns: { matches: true, params: {} }
`

Supported patterns (three types with different hostname matching):

1. Pathname-only patterns (origin-agnostic - match ANY hostname)

- Path params: /users/:id, /posts/:postId/comments/:commentId
- Exact: /api/users
- Wildcards: /api/, /users/*

2. Full URL patterns (hostname-specific - match ONLY specified hostname)

- Exact: https://api.example.com/users
- Path params: https://api.example.com/users/:id
- Wildcards: https:///users, https://api.example.com/

3. Native RegExp (origin-agnostic - MSW weak comparison)

- /\/api\/v\d+\// (matches /api/v1/, /api/v2/, etc.)
- /\/users\/\d+$/ (matches /users/123 at any origin)

IMPORTANT: If you specify a hostname in a full URL pattern, it WILL be matched. Choose pathname patterns for environment-agnostic mocks, full URL patterns when hostname matters.

$3

Finds the right mock for a request:

`typescript
import { findMatchingMock } from '@scenarist/msw-adapter';

const mocks: ScenaristMock[] = [
{ method: 'GET', url: '/users/:id', response: { status: 200, body: {...} } },
{ method: 'POST', url: '/users', response: { status: 201, body: {...} } },
];

const mock = findMatchingMock(mocks, 'GET', 'https://api.example.com/users/123');
// Returns the first mock (matches /users/:id)
`

$3

Converts ScenaristMock to MSW HttpResponse:

`typescript
import { buildResponse } from "@scenarist/msw-adapter";

const mockDef: ScenaristMock = {
method: "GET",
url: "/api/user",
response: {
status: 200,
body: { id: "123", name: "John" },
headers: { "X-Custom": "value" },
delay: 100,
},
};

const response = await buildResponse(mockDef);
// Returns MSW HttpResponse with status, body, headers, and delay
`

$3

The core integration - a single MSW handler that routes dynamically:

`typescript
import { createDynamicHandler } from "@scenarist/msw-adapter";
import { setupServer } from "msw/node";

const handler = createDynamicHandler({
getTestId: () => testIdStorage.getStore() ?? "default-test",
getActiveScenario: (testId) => manager.getActiveScenario(testId),
getScenarioDefinition: (scenarioId) => manager.getScenarioById(scenarioId),
strictMode: false,
});

const server = setupServer(handler);
server.listen();
`

How it works:

1. Gets test ID from AsyncLocalStorage (or other context)
2. Looks up active scenario for that test ID
3. Collects mocks from BOTH default AND active scenario for matching URL + method
4. Uses specificity-based selection to choose best match
5. Active scenario mocks (with match criteria) override default mocks (no criteria)
6. Returns mocked response or passthrough (if no match found)

Key insight: Default scenario mocks are ALWAYS collected first, then active scenario mocks are added. The specificity algorithm (from ResponseSelector) chooses the most specific match. This means specialized scenarios only need to define what changes - everything else automatically falls back to default.

Architecture

This package is designed to be framework-agnostic. Framework adapters (Express, Next.js, etc.) handle:

- Test ID extraction (from headers, context, etc.)
- Scenario management (switching, retrieving)
- Middleware integration

The MSW adapter handles:

- URL matching and pattern conversion
- Mock finding and selection
- Response building
- MSW handler creation

API Reference

$3

`typescript
export const matchesUrl = (
requestUrl: string,
method: string,
pattern: string
): { matches: boolean; params: Record };
`

$3

`typescript
export const findMatchingMock = (
mocks: ReadonlyArray,
method: string,
url: string
): ScenaristMock | undefined;
`

$3

`typescript
export const buildResponse = (
mockDef: ScenaristMock
): Promise;
`

$3

`typescript
export type DynamicHandlerOptions = {
readonly getTestId: () => string;
readonly getActiveScenario: (testId: string) => ActiveScenario | undefined;
readonly getScenarioDefinition: (scenarioId: string) => ScenaristScenario | undefined;
readonly strictMode: boolean;
};

export const createDynamicHandler = (
options: DynamicHandlerOptions
): HttpHandler;
`

TypeScript

Full TypeScript support with strict mode enabled.

Exported types:

`typescript
import type { DynamicHandlerOptions } from "@scenarist/msw-adapter";
``

Testing

This package has comprehensive test coverage:

- ✅ URL matching (exact, glob, path params)
- ✅ Mock matching (method, URL, precedence)
- ✅ Response building (status, body, headers, delays)
- ✅ Dynamic handler (scenarios, fallback, strict mode)
- ✅ 31 tests passing

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT

Related Packages

- @scenarist/core - Core scenario management
- @scenarist/express-adapter - Express integration (uses this package)