@r0hitsharma/http-client-msw 0.12.0-rohit-fork-ci.1

package/src/base-url.test.ts

@@ -0,0 +1,177 @@
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import { describe, expect, it } from 'vitest';
+
+import {
+  isAbsoluteUrl,
+  type MockOriginMatching,
+  normalizeApiBaseUrl,
+  resolveHandlerBase,
+  resolveWorkerScriptUrl,
+} from './base-url.js';
+
+describe('normalizeApiBaseUrl', () => {
+  it('is empty when no base is given', () => {
+    expect(normalizeApiBaseUrl()).toBe('');
+    expect(normalizeApiBaseUrl('')).toBe('');
+  });
+
+  it('strips trailing slashes so a prefixed path never doubles up', () => {
+    expect(normalizeApiBaseUrl('/api')).toBe('/api');
+    expect(normalizeApiBaseUrl('/api/')).toBe('/api');
+    expect(normalizeApiBaseUrl('/api//')).toBe('/api');
+    expect(normalizeApiBaseUrl('/')).toBe('');
+  });
+
+  it('keeps an absolute base intact', () => {
+    expect(normalizeApiBaseUrl('https://api.test/v1/')).toBe(
+      'https://api.test/v1',
+    );
+  });
+});
+
+describe('isAbsoluteUrl', () => {
+  it('distinguishes an origin-relative base from an absolute one', () => {
+    expect(isAbsoluteUrl('http://localhost:3000/api')).toBe(true);
+    expect(isAbsoluteUrl('https://api.test')).toBe(true);
+    expect(isAbsoluteUrl('/api')).toBe(false);
+    expect(isAbsoluteUrl('')).toBe(false);
+  });
+
+  it('does not count a protocol-relative base, which carries no scheme', () => {
+    expect(isAbsoluteUrl('//api.test/v1')).toBe(false);
+  });
+});
+
+describe('resolveHandlerBase', () => {
+  it('wildcards the origin of a relative base by default', () => {
+    expect(resolveHandlerBase('/api', 'any')).toBe('*/api');
+    expect(resolveHandlerBase('/api/', 'any')).toBe('*/api');
+    expect(resolveHandlerBase(undefined, 'any')).toBe('*');
+  });
+
+  it('keeps a relative base relative when matching exactly', () => {
+    expect(resolveHandlerBase('/api', 'exact')).toBe('/api');
+    expect(resolveHandlerBase(undefined, 'exact')).toBe('');
+  });
+
+  it('leaves an absolute base alone, since it already pins the origin', () => {
+    expect(resolveHandlerBase('https://api.test/v1/', 'any')).toBe(
+      'https://api.test/v1',
+    );
+    expect(resolveHandlerBase('https://api.test/v1', 'exact')).toBe(
+      'https://api.test/v1',
+    );
+  });
+
+  it('wildcards a protocol-relative base under either setting', () => {
+    expect(resolveHandlerBase('//api.test/v1/', 'any')).toBe('*//api.test/v1');
+    expect(resolveHandlerBase('//api.test/v1', 'exact')).toBe('*//api.test/v1');
+  });
+});
+
+/**
+ * The contract that actually matters is whether msw matches, not what string
+ * comes back — a resolved base can read perfectly and still match nothing, at
+ * which point the request escapes to the real network instead of failing.
+ *
+ * So these drive the resolved base through `setupServer`. The trailing
+ * catch-all is what makes them match tests: msw resolves handlers in
+ * declaration order, so a request the resolved base does not match falls
+ * through to the sentinel rather than reaching the network, and the assertion
+ * is which of the two answered.
+ */
+const answeredBy = async (
+  baseUrl: string | undefined,
+  origin: MockOriginMatching,
+  url: string,
+): Promise<'base' | 'sentinel'> => {
+  const server = setupServer(
+    http.get(`${resolveHandlerBase(baseUrl, origin)}/things`, () =>
+      HttpResponse.json('base'),
+    ),
+    http.all(/.*/, () => HttpResponse.json('sentinel')),
+  );
+
+  server.listen({ onUnhandledRequest: 'error' });
+  try {
+    return (await (await fetch(url)).json()) as 'base' | 'sentinel';
+  } finally {
+    server.close();
+  }
+};
+
+describe('resolveHandlerBase — matching under msw', () => {
+  it('matches a protocol-relative base on either scheme', async () => {
+    await expect(
+      answeredBy('//api.test/v1', 'any', 'http://api.test/v1/things'),
+    ).resolves.toBe('base');
+    await expect(
+      answeredBy('//api.test/v1', 'any', 'https://api.test/v1/things'),
+    ).resolves.toBe('base');
+    await expect(
+      answeredBy('//api.test/v1', 'exact', 'https://api.test/v1/things'),
+    ).resolves.toBe('base');
+  });
+
+  it('still pins the host of a protocol-relative base', async () => {
+    await expect(
+      answeredBy('//api.test/v1', 'any', 'https://elsewhere.test/v1/things'),
+    ).resolves.toBe('sentinel');
+  });
+
+  it('matches an absolute base on its own scheme and host only', async () => {
+    await expect(
+      answeredBy('https://api.test/v1/', 'any', 'https://api.test/v1/things'),
+    ).resolves.toBe('base');
+    await expect(
+      answeredBy('https://api.test/v1', 'any', 'http://api.test/v1/things'),
+    ).resolves.toBe('sentinel');
+    await expect(
+      answeredBy('https://api.test/v1', 'any', 'https://other.test/v1/things'),
+    ).resolves.toBe('sentinel');
+  });
+
+  it('matches any origin when no base is given', async () => {
+    await expect(
+      answeredBy(undefined, 'any', 'http://localhost/things'),
+    ).resolves.toBe('base');
+    await expect(
+      answeredBy(undefined, 'any', 'https://api.test/things'),
+    ).resolves.toBe('base');
+  });
+
+  it('matches any origin for a relative base by default', async () => {
+    await expect(
+      answeredBy('/api', 'any', 'http://localhost/api/things'),
+    ).resolves.toBe('base');
+    await expect(
+      answeredBy('/api', 'any', 'https://api.test/api/things'),
+    ).resolves.toBe('base');
+  });
+
+  it('matches nothing in node for a relative base under `exact`', async () => {
+    // The documented cost of opting out: node request URLs are always
+    // absolute, so the relative pattern never matches and a node test needs an
+    // absolute `baseUrl` of its own.
+    await expect(
+      answeredBy('/api', 'exact', 'http://localhost/api/things'),
+    ).resolves.toBe('sentinel');
+  });
+});
+
+describe('resolveWorkerScriptUrl', () => {
+  it('serves from the root by default', () => {
+    expect(resolveWorkerScriptUrl()).toBe('/mockServiceWorker.js');
+    expect(resolveWorkerScriptUrl('')).toBe('/mockServiceWorker.js');
+    expect(resolveWorkerScriptUrl('/')).toBe('/mockServiceWorker.js');
+  });
+
+  it('follows the app base path for a subpath deployment', () => {
+    expect(resolveWorkerScriptUrl('/app')).toBe('/app/mockServiceWorker.js');
+    expect(resolveWorkerScriptUrl('/app/')).toBe('/app/mockServiceWorker.js');
+    expect(resolveWorkerScriptUrl('/nested/app/')).toBe(
+      '/nested/app/mockServiceWorker.js',
+    );
+  });
+});

package/src/base-url.ts

@@ -0,0 +1,80 @@
+/**
+ * Two different base URLs live in this package and they normalize to opposite
+ * shapes, so both live here rather than being inlined at their call sites:
+ *
+ * - the **API** base (`createMockApi({ baseUrl })`) is prepended to OpenAPI path
+ *   templates, which already start with `/`, so it must not end in one;
+ * - the **app** base (`setupMockWorker(mocks, { baseUrl })`) is the public base
+ *   path a subpath deployment is served from, and the worker script filename is
+ *   appended to it, so it must end in one.
+ */
+
+/** How an origin-relative API base is matched. See {@link resolveHandlerBase}. */
+export type MockOriginMatching = 'any' | 'exact';
+
+/** A scheme plus authority — `https://api.test`. Pins both scheme and host. */
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:\/\//i;
+
+/** A protocol-relative `//api.test` — pins the host, leaves the scheme open. */
+const PROTOCOL_RELATIVE_URL = /^\/\//;
+
+/**
+ * Whether the base carries its own scheme. A protocol-relative `//host` does
+ * not, and so is *not* absolute here — see {@link resolveHandlerBase}, which
+ * has to prefix one for msw to match it at all.
+ */
+export function isAbsoluteUrl(url: string): boolean {
+  return ABSOLUTE_URL.test(url);
+}
+
+/** Strips trailing slashes so `${base}${'/things'}` never doubles up. */
+export function normalizeApiBaseUrl(baseUrl?: string): string {
+  if (!baseUrl) return '';
+
+  return baseUrl.replace(/\/+$/, '');
+}
+
+/**
+ * The prefix every handler path is built on.
+ *
+ * msw resolves a relative handler path against `document.baseURI` in the browser
+ * and leaves it relative in node, where request URLs are always absolute — so a
+ * relative path silently matches nothing under `setupServer`. Prefixing an
+ * origin-relative base with msw's `*` wildcard makes one handler array match in
+ * both, which is what lets the same mocks serve dev, vitest, and Playwright.
+ *
+ * `'exact'` opts out and keeps the path relative — same-origin matching only,
+ * and node tests then need an absolute `baseUrl`. An absolute base already pins
+ * the origin, so the setting does not apply to one.
+ *
+ * A protocol-relative `//host` is prefixed under *both* settings. It pins the
+ * host but not the scheme, and msw matches a bare `//host` pattern against
+ * neither `http:` nor `https:` — the request escapes to the real network. The
+ * wildcard stands in for the scheme only, so the host stays pinned.
+ */
+export function resolveHandlerBase(
+  baseUrl: string | undefined,
+  origin: MockOriginMatching,
+): string {
+  const normalized = normalizeApiBaseUrl(baseUrl);
+
+  if (isAbsoluteUrl(normalized)) return normalized;
+
+  const pinsHost = PROTOCOL_RELATIVE_URL.test(normalized);
+
+  if (origin === 'exact' && !pinsHost) return normalized;
+
+  return `*${normalized}`;
+}
+
+/**
+ * The URL msw's service worker script is served from. It follows the app's
+ * public base path — `import.meta.env.BASE_URL` under Vite — because a bundler
+ * copies `public/mockServiceWorker.js` to `${base}mockServiceWorker.js`, and the
+ * worker's scope is limited to the directory it is served from.
+ */
+export function resolveWorkerScriptUrl(baseUrl?: string): string {
+  const base = baseUrl && baseUrl.length > 0 ? baseUrl : '/';
+
+  return `${base.endsWith('/') ? base : `${base}/`}mockServiceWorker.js`;
+}

package/src/browser.ts

@@ -0,0 +1,88 @@
+/**
+ * Browser entry: `@r0hitsharma/http-client-msw/browser`.
+ *
+ * Kept behind its own subpath so `msw/browser` — and the service-worker
+ * machinery it pulls in — never reaches a node test's module graph, and so an
+ * app bundle that imports only this entry does not drag in `msw/node`.
+ */
+
+import { setupWorker, type SetupWorker } from 'msw/browser';
+
+import type { MockSetup } from './setup.js';
+import {
+  buildWorkerStartOptions,
+  createIdempotentStart,
+  type MockWorkerOptions,
+} from './worker-options.js';
+
+/**
+ * Re-exported here rather than from the package root: their types reference
+ * `msw/browser`, which does not resolve under a node-only condition set.
+ */
+export {
+  buildWorkerStartOptions,
+  createIdempotentStart,
+  type IdempotentStart,
+  type MockWorkerOptions,
+} from './worker-options.js';
+
+export type MockWorker = {
+  /** The underlying msw worker, for `use()` and lifecycle events. */
+  worker: SetupWorker;
+  /** Registers and activates the worker. Idempotent; safe to await anywhere. */
+  start: () => Promise<void>;
+  /** Stops interception. A later `start()` re-registers the worker. */
+  stop: () => void;
+  /** Runs the setup's state resets, then drops runtime handler overrides. */
+  reset: () => void;
+};
+
+/**
+ * Serves a {@link MockSetup} from a service worker.
+ *
+ * Call `start()` and await it **before** rendering, so no component can fire a
+ * request the worker is not yet intercepting:
+ *
+ * ```ts
+ * // src/main.tsx
+ * if (import.meta.env.VITE_API_MOCKS === '1') {
+ *   const { setupMockWorker } = await import(
+ *     '@r0hitsharma/http-client-msw/browser'
+ *   );
+ *   const { mocks } = await import('./mocks');
+ *
+ *   await setupMockWorker(mocks, { baseUrl: import.meta.env.BASE_URL }).start();
+ * }
+ *
+ * createRoot(document.getElementById('root')!).render(<App />);
+ * ```
+ *
+ * The dynamic imports are what keep msw and the fixtures out of a production
+ * bundle: with a statically analysable `import.meta.env` flag, the whole branch
+ * is dead code a bundler drops.
+ */
+export function setupMockWorker(
+  mocks: MockSetup,
+  options: MockWorkerOptions = {},
+): MockWorker {
+  const worker = setupWorker(...mocks.handlers);
+  const startOptions = buildWorkerStartOptions(options);
+  const { start, invalidate } = createIdempotentStart(async () => {
+    await worker.start(startOptions);
+  });
+
+  return {
+    worker,
+    start,
+    stop: () => {
+      worker.stop();
+      // A stopped worker intercepts nothing, so the next `start()` has to
+      // re-register rather than resolve from the memo.
+      invalidate();
+    },
+    reset: () => {
+      mocks.resetState();
+      worker.resetHandlers();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Typed msw mocks keyed off a generated OpenAPI `paths` type — the same type
+ * that drives `createApiClient` and `createQueryApi`, so handlers, params, and
+ * fixture bodies are checked against one contract.
+ *
+ * Environment wiring lives behind subpath entries so neither environment's msw
+ * import ends up in the other's bundle:
+ *
+ * - `@r0hitsharma/http-client-msw/browser` — `setupMockWorker`
+ * - `@r0hitsharma/http-client-msw/node` — `setupMockServer`
+ *
+ * Nothing here references `msw/browser` or `msw/node`, so this entry stays
+ * resolvable from either environment.
+ */
+
+export {
+  createMockApi,
+  type MockApi,
+  type MockApiOptions,
+  type MockHandler,
+  type MockOriginMatching,
+  type MockPathsFor,
+  type MockRequestBodyFor,
+  type MockRequestHandler,
+  type MockResponseBodyFor,
+  type MockResponseResolver,
+  type MockResponseResolverInfo,
+} from './mock-api.js';
+export {
+  isAbsoluteUrl,
+  normalizeApiBaseUrl,
+  resolveHandlerBase,
+  resolveWorkerScriptUrl,
+} from './base-url.js';
+export {
+  isTestEnvironment,
+  mockDelay,
+  type MockDelayInput,
+  resolveMockDelay,
+} from './mock-delay.js';
+export {
+  createMockStore,
+  type MockStore,
+  type MockStoreOptions,
+} from './mock-store.js';
+export { createSeededRng, type SeededRng } from './seeded-rng.js';
+export {
+  type MockResetCallback,
+  type MockSetup,
+  type MockSetupHandler,
+  type MockSetupOptions,
+  setupMocks,
+} from './setup.js';

package/src/mock-api.test.ts

@@ -0,0 +1,148 @@
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import { createMockApi } from './mock-api.js';
+import { type Thing, type TestPaths, seedThings } from './test-fixtures.js';
+
+const mock = createMockApi<TestPaths>();
+
+const server = setupServer();
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe('createMockApi', () => {
+  it('responds with the operation 2xx body', async () => {
+    server.use(
+      mock.get('/things', ({ response }) => response(200).json(seedThings())),
+    );
+
+    const response = await fetch('http://localhost/things');
+
+    expect(response.status).toBe(200);
+    expect((await response.json()) as Thing[]).toEqual(seedThings());
+  });
+
+  it('parses the OpenAPI path template into typed path params', async () => {
+    server.use(
+      mock.get('/things/{id}', ({ params, response }) =>
+        response(200).json({
+          id: params.id,
+          name: `thing-${params.id}`,
+          size: 3,
+        }),
+      ),
+    );
+
+    const response = await fetch('http://localhost/things/t7');
+
+    expect(await response.json()).toEqual({
+      id: 't7',
+      name: 'thing-t7',
+      size: 3,
+    });
+  });
+
+  it('exposes query params through the typed query helper', async () => {
+    server.use(
+      mock.get('/things', ({ query, response }) => {
+        const limit = Number(query.get('limit') ?? '0');
+
+        return response(200).json(seedThings().slice(0, limit));
+      }),
+    );
+
+    const response = await fetch('http://localhost/things?limit=1');
+
+    expect(await response.json()).toEqual([seedThings()[0]]);
+  });
+
+  it('reads a typed request body off a mutating operation', async () => {
+    server.use(
+      mock.post('/things', async ({ request, response }) => {
+        const body = await request.json();
+
+        return response(201).json({ id: 'new', ...body });
+      }),
+    );
+
+    const response = await fetch('http://localhost/things', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Fresh', size: 9 }),
+    });
+
+    expect(response.status).toBe(201);
+    expect(await response.json()).toEqual({
+      id: 'new',
+      name: 'Fresh',
+      size: 9,
+    });
+  });
+
+  it('answers with a declared error status and body', async () => {
+    server.use(
+      mock.get('/things/{id}', ({ response }) =>
+        response(404).json({ message: 'no such thing' }),
+      ),
+    );
+
+    const response = await fetch('http://localhost/things/missing');
+
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ message: 'no such thing' });
+  });
+
+  it('answers a no-content operation with an empty body', async () => {
+    server.use(
+      mock.delete('/things/{id}', ({ response }) => response(204).empty()),
+    );
+
+    const response = await fetch('http://localhost/things/t1', {
+      method: 'DELETE',
+    });
+
+    expect(response.status).toBe(204);
+    expect(await response.text()).toBe('');
+  });
+
+  it('prefixes handler paths with a relative baseUrl on any origin', async () => {
+    const prefixed = createMockApi<TestPaths>({ baseUrl: '/api' });
+    server.use(
+      prefixed.get('/things', ({ response }) =>
+        response(200).json(seedThings()),
+      ),
+    );
+
+    for (const origin of ['http://localhost', 'https://elsewhere.test']) {
+      const response = await fetch(`${origin}/api/things`);
+
+      expect(response.status).toBe(200);
+      expect(await response.json()).toEqual(seedThings());
+    }
+  });
+
+  it('tolerates a trailing slash on baseUrl', async () => {
+    const prefixed = createMockApi<TestPaths>({ baseUrl: '/api/' });
+    server.use(
+      prefixed.get('/things', ({ response }) => response(200).json([])),
+    );
+
+    const response = await fetch('http://localhost/api/things');
+
+    expect(response.status).toBe(200);
+  });
+
+  it('pins the origin when baseUrl is absolute', async () => {
+    const prefixed = createMockApi<TestPaths>({
+      baseUrl: 'http://localhost/api',
+    });
+    server.use(
+      prefixed.get('/things', ({ response }) => response(200).json([])),
+    );
+
+    expect((await fetch('http://localhost/api/things')).status).toBe(200);
+    await expect(fetch('https://elsewhere.test/api/things')).rejects.toThrow();
+  });
+});

package/src/mock-api.ts

@@ -0,0 +1,96 @@
+import { createOpenApiHttp, type OpenApiHttpHandlers } from 'openapi-msw';
+
+import { type MockOriginMatching, resolveHandlerBase } from './base-url.js';
+
+/**
+ * The msw handler types this package's surface is expressed in. They are
+ * re-exported so a consumer writing a helper around a resolver types against
+ * the copy of msw this package resolves, rather than importing msw types in one
+ * file and ours in another.
+ */
+export type {
+  HttpHandler as MockHandler,
+  RequestHandler as MockRequestHandler,
+} from 'msw';
+export type { MockOriginMatching } from './base-url.js';
+export type {
+  ResponseResolver as MockResponseResolver,
+  ResponseResolverInfo as MockResponseResolverInfo,
+} from 'openapi-msw';
+export type {
+  PathsFor as MockPathsFor,
+  RequestBodyFor as MockRequestBodyFor,
+  ResponseBodyFor as MockResponseBodyFor,
+} from 'openapi-msw';
+
+export type MockApiOptions = {
+  /**
+   * Prepended to every handler path, for an API mounted under a prefix. Given
+   * `'/api'`, a handler declared on `/things/{id}` matches `/api/things/:id`.
+   * Pass the same value the app passes to `createApiClient`.
+   *
+   * Either an origin-relative path with a leading slash (`'/api'`) or an absolute
+   * URL (`'https://api.test/v1'`); a trailing slash is tolerated. It is
+   * concatenated with the OpenAPI path, so anything else — a query string, a
+   * fragment, a missing leading slash — yields a pattern that matches nothing,
+   * which surfaces as an unhandled request rather than an error.
+   */
+  baseUrl?: string;
+  /**
+   * How an origin-relative `baseUrl` is matched.
+   *
+   * - `'any'` (default) prefixes handler paths with msw's `*` origin wildcard, so
+   *   one handler array matches both the relative request a browser app makes
+   *   and the absolute URL a node test has to issue. That is what makes the same
+   *   mocks reusable across dev, vitest, and Playwright.
+   * - `'exact'` leaves paths relative: same-origin matching only, and a node
+   *   test then needs an absolute `baseUrl` of its own.
+   *
+   * An absolute `baseUrl` already pins the origin, so this does not apply to
+   * one.
+   */
+  origin?: MockOriginMatching;
+};
+
+/**
+ * A typed handler factory per HTTP method, plus `untyped` — msw's own `http`
+ * object, for the rare route that is not in the OpenAPI document at all (an
+ * auth callback on another host, say).
+ */
+export type MockApi<TPaths extends object> = OpenApiHttpHandlers<TPaths>;
+
+/**
+ * Creates typed msw request-handler factories bound to a generated OpenAPI
+ * `paths` type.
+ *
+ * The generated `TPaths` is the only endpoint definition: which methods exist on
+ * which paths, what path and query params they take, and what body each status
+ * may return are all read off it. A handler for a path the API does not have, or
+ * one that answers with a body the operation does not declare, fails to compile
+ * — which is the whole point of the layer, since a fixture that silently drifts
+ * from the contract makes every test that depends on it a false pass.
+ *
+ * `TPaths` must be passed explicitly; there is no value argument to infer it
+ * from — which is why the constraint is `object` rather than the `{}` that
+ * openapi-msw itself accepts. Every primitive but `null` and `undefined`
+ * satisfies `{}`, so a mistyped type argument compiled into a factory offering
+ * no paths at all.
+ *
+ * ```ts
+ * const mock = createMockApi<paths>({ baseUrl: '/api' });
+ *
+ * const handlers = [
+ *   mock.get('/things/{id}', ({ params, response }) =>
+ *     response(200).json({ id: params.id, name: 'Thing' }),
+ *   ),
+ *   mock.get('/things', ({ response }) => response(500).json({ message: 'nope' })),
+ * ];
+ * ```
+ */
+export function createMockApi<TPaths extends object>(
+  options: MockApiOptions = {},
+): MockApi<TPaths> {
+  return createOpenApiHttp<TPaths>({
+    baseUrl: resolveHandlerBase(options.baseUrl, options.origin ?? 'any'),
+  });
+}