@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:

Request Matching (6 capabilities)

• 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

Response Sequences (4 capabilities)

• 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

Stateful Mocks (6 capabilities)

• 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

URL Patterns (4 capabilities)

• 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)

MSW Integration (6 capabilities)

• 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

1. URL Matching

Converts string patterns into MSW-compatible URL matchers:

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.

2. Mock Matching

Finds the right mock for a request:

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. Response Building

Converts ScenaristMock to MSW HttpResponse:

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

4. Dynamic Handler

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

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

URL Matching

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

Mock Matching

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

Response Building

export const buildResponse = (
  mockDef: ScenaristMock
): Promise<HttpResponse>;

Dynamic Handler

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:

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)