@yabbadabbadev/pepito 0.1.0

package/dist/failure-messages.js

@@ -0,0 +1,145 @@
+import { matchesSpec } from './spec-matching';
+const TRAFFIC_FLAGS = ['matched', 'mocked', 'bypassed', 'unhandled'];
+function formatQuery(searchParams) {
+    const query = new URLSearchParams(searchParams).toString();
+    return query ? `?${query}` : '';
+}
+function formatFlags(entry) {
+    const activeFlags = TRAFFIC_FLAGS.filter((flag) => entry[flag]);
+    return activeFlags.length > 0 ? activeFlags.join('/') : 'no verdict';
+}
+function formatTrafficLine(entry) {
+    const status = entry.status ?? '(no response)';
+    return `  ${entry.method} ${entry.path}${formatQuery(entry.searchParams)} → ${status} [${formatFlags(entry)}]`;
+}
+/** Dumps the observed traffic, one line per entry, to embed in a failure message. */
+export function formatTraffic(traffic) {
+    if (traffic.length === 0)
+        return '  (no traffic observed)';
+    return traffic.map(formatTrafficLine).join('\n');
+}
+// Only what identifies the expected request, not the comparison options
+// (`exact`): that's a mode of matchesSpec, not something one "expected to
+// receive".
+function describeSpec(spec) {
+    return {
+        method: spec.method,
+        path: spec.path,
+        searchParams: spec.searchParams,
+        body: spec.body,
+    };
+}
+/**
+ * Composes the network matchers' failure message: the matcher's hint, what
+ * was expected, a diff against the closest candidate (same method and path,
+ * even if it doesn't fully match) if one exists, and the full dump of the
+ * observed traffic.
+ */
+export function requestFailureMessage(messageContext) {
+    const { utils, matcherName, spec, traffic, isNot } = messageContext;
+    const sections = [
+        utils.matcherHint(matcherName, undefined, undefined, { isNot }),
+        // Under `.not`, what failed is that there WAS a matching request: the
+        // hint already says so with the "not.", but the "Expected" line by
+        // itself would still read as the positive case if it didn't change
+        // along with it.
+        isNot
+            ? `Not expected: ${utils.printExpected(describeSpec(spec))}`
+            : `Expected: ${utils.printExpected(describeSpec(spec))}`,
+    ];
+    const candidate = traffic.find((entry) => entry.method === spec.method && entry.path === spec.path);
+    if (candidate) {
+        const diff = utils.diff({ searchParams: spec.searchParams, body: spec.body }, { searchParams: candidate.searchParams, body: candidate.body });
+        if (diff)
+            sections.push(diff);
+    }
+    sections.push(`Observed traffic:\n${formatTraffic(traffic)}`);
+    return sections.join('\n\n');
+}
+/**
+ * Composes the `toHaveBeenRequestedTimes` failure message: there's no
+ * "closest candidate" to show like in `requestFailureMessage`, but an
+ * expected count against the one actually observed, plus the full dump.
+ */
+export function requestCountFailureMessage(messageContext) {
+    const { utils, spec, expectedCount, foundCount, traffic, isNot } = messageContext;
+    // Under `.not`, `foundCount` is necessarily equal to `expectedCount` (that's
+    // what made the negated assertion fail): a bare "found 2" would read as a
+    // meaningless echo if it didn't also say that count is exactly the one
+    // that wasn't expected.
+    const leadLine = isNot
+        ? `Did not expect exactly ${expectedCount} request(s) to ${utils.printExpected(describeSpec(spec))}, yet found ${foundCount}`
+        : `Expected ${expectedCount} request(s) to ${utils.printExpected(describeSpec(spec))}, found ${foundCount}`;
+    const sections = [
+        utils.matcherHint('toHaveBeenRequestedTimes', undefined, undefined, {
+            isNot,
+        }),
+        leadLine,
+        `Observed traffic:\n${formatTraffic(traffic)}`,
+    ];
+    return sections.join('\n\n');
+}
+/**
+ * Composes the `toHaveNoUnhandledRequests` failure message: which requests
+ * arrived without a handler (method and path, the minimum needed to locate
+ * them in the code) followed by the full traffic dump, in case the missing
+ * handler becomes obvious when seen alongside the rest.
+ */
+export function noUnhandledRequestsFailureMessage(messageContext) {
+    const { utils, unhandledEntries, traffic, isNot } = messageContext;
+    // Under `.not`, what failed is that `unhandledEntries` is EMPTY — listing
+    // "Unhandled requests:" followed by nothing is the bug this `isNot`
+    // fixes: the negated assertion demanded traffic without a handler and
+    // there was none.
+    const leadLine = isNot
+        ? 'Expected to find some request without a handler, but the traffic came in clean'
+        : `Unhandled requests:\n${unhandledEntries
+            .map((entry) => `  ${entry.method} ${entry.path}`)
+            .join('\n')}`;
+    const sections = [
+        utils.matcherHint('toHaveNoUnhandledRequests', undefined, undefined, {
+            isNot,
+        }),
+        leadLine,
+        `Observed traffic:\n${formatTraffic(traffic)}`,
+    ];
+    return sections.join('\n\n');
+}
+function describeExpectedResponse(expected) {
+    return expected.body === undefined
+        ? { status: expected.status }
+        : { status: expected.status, body: expected.body };
+}
+/**
+ * Composes the `toHaveRespondedWith` failure message: the matcher's hint,
+ * the expected response, a diff against the closest intercepted-and-matched
+ * candidate (even if it doesn't match on status or body) if one exists, and
+ * the full dump of the observed traffic. The candidate requires `matched &&
+ * mocked` because a passthrough entry can match the request's spec without
+ * ever having been intercepted: showing it as "close" would be misleading.
+ */
+export function respondedWithFailureMessage(messageContext) {
+    const { utils, spec, expected, traffic, isNot } = messageContext;
+    const leadLine = isNot
+        ? `Not expected: ${utils.printExpected(describeSpec(spec))} responded with ${utils.printExpected(describeExpectedResponse(expected))}`
+        : `Expected: ${utils.printExpected(describeSpec(spec))} responded with ${utils.printExpected(describeExpectedResponse(expected))}`;
+    const sections = [
+        utils.matcherHint('toHaveRespondedWith', undefined, undefined, { isNot }),
+        leadLine,
+    ];
+    const candidate = traffic.find((entry) => entry.matched && entry.mocked && matchesSpec(entry, spec));
+    if (candidate) {
+        // Same key (`body`) on both sides, and absent on both if `expected`
+        // doesn't carry it: with different names (`body` vs `responseBody`) the
+        // diff finds no common ground and shows two whole unrelated blocks
+        // instead of pointing at the field that actually changed inside the
+        // body.
+        const diff = utils.diff(describeExpectedResponse(expected), expected.body === undefined
+            ? { status: candidate.status }
+            : { status: candidate.status, body: candidate.responseBody });
+        if (diff)
+            sections.push(diff);
+    }
+    sections.push(`Observed traffic:\n${formatTraffic(traffic)}`);
+    return sections.join('\n\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import './matchers';
+import './matcher-types';
+export * from './request-descriptors';
+export { setupNetwork } from './setup-network';
+export { network } from './network';
+export { mount } from './mount';
+export type { MountOptions } from './mount';

package/dist/index.js

@@ -0,0 +1,6 @@
+import './matchers';
+import './matcher-types';
+export * from './request-descriptors';
+export { setupNetwork } from './setup-network';
+export { network } from './network';
+export { mount } from './mount';

package/dist/matcher-types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * What a handler is expected to have responded, for `toHaveRespondedWith`.
+ * `status` is required; `body` is compared by subset of top-level keys
+ * unless `exact: true`, which requires strict equality — same semantics as
+ * `RequestSpecOptions.body` in request-descriptors.ts, but over the
+ * response instead of the request.
+ */
+export interface ExpectedResponse {
+    status: number;
+    body?: unknown;
+    exact?: boolean;
+}
+interface NetworkMatchers<ReturnType = unknown> {
+    /**
+     * Checks that the application made a request matching `spec`, by exact
+     * `method` and `path` and `searchParams`/`body` by subset. Retries until
+     * it finds one or the timeout runs out: a request is an effect that
+     * follows an interaction, same as `expect.element`.
+     *
+     * `.not.toHaveBeenRequested()` does not retry: it waits for the network to
+     * settle first, so as not to mistake a request that hasn't arrived yet for
+     * one that was never made.
+     *
+     * @example
+     * ```ts
+     * import { get } from '@yabbadabbadev/pepito'
+     *
+     * await fetch('/api/products')
+     * await expect(get('/api/products')).toHaveBeenRequested()
+     * await expect(get('/api/other')).not.toHaveBeenRequested()
+     * ```
+     */
+    toHaveBeenRequested(): Promise<ReturnType>;
+    /**
+     * Checks that exactly `count` requests matching `spec` were made. Always
+     * waits for the network to settle before counting, with or without
+     * `.not`: a count taken mid-traffic is as false as an absence taken
+     * mid-traffic.
+     *
+     * @example
+     * ```ts
+     * import { get } from '@yabbadabbadev/pepito'
+     *
+     * await Promise.all([fetch('/api/products'), fetch('/api/products')])
+     * await expect(get('/api/products')).toHaveBeenRequestedTimes(2)
+     * ```
+     */
+    toHaveBeenRequestedTimes(count: number): Promise<ReturnType>;
+    /**
+     * Checks that one of your own handlers produced the response, not
+     * just that the request matched its route: a handler with `passthrough()`
+     * satisfies `toHaveBeenRequested` but not this matcher, because the
+     * response came from the real network.
+     *
+     * @example
+     * ```ts
+     * import { post } from '@yabbadabbadev/pepito'
+     *
+     * await fetch('/api/products', { method: 'POST' })
+     * await expect(post('/api/products')).toHaveBeenIntercepted()
+     * ```
+     */
+    toHaveBeenIntercepted(): Promise<ReturnType>;
+    /**
+     * Checks that the request was intercepted (like `toHaveBeenIntercepted`)
+     * and that the response has the expected `status` and, if given, a `body`
+     * that matches by subset. `toHaveRespondedWith(500)` is the shorthand for
+     * `toHaveRespondedWith({ status: 500 })`.
+     *
+     * @example
+     * ```ts
+     * import { get } from '@yabbadabbadev/pepito'
+     *
+     * await fetch('/api/products')
+     * await expect(get('/api/products')).toHaveRespondedWith({
+     *   status: 200,
+     *   body: { total: 2 },
+     * })
+     * ```
+     */
+    toHaveRespondedWith(expected: number | ExpectedResponse): Promise<ReturnType>;
+    /**
+     * Suite guardrail: checks that no request was left without a handler. It
+     * does not describe a specific request, so it hangs off `expect.network()`
+     * instead of a `get`/`post`/… descriptor; using it on anything else fails
+     * with an instruction, not a data verdict.
+     *
+     * @example
+     * ```ts
+     * await expect.network().toHaveNoUnhandledRequests()
+     * ```
+     */
+    toHaveNoUnhandledRequests(): Promise<ReturnType>;
+}
+declare module '@vitest/expect' {
+    interface Assertion<T = any> extends NetworkMatchers<T> {
+    }
+    interface AsymmetricMatchersContaining extends NetworkMatchers {
+    }
+    interface ExpectStatic {
+        /**
+         * Entry point for assertions over the network as a whole, not over a
+         * specific request. Today only `toHaveNoUnhandledRequests` consumes it.
+         *
+         * @example
+         * ```ts
+         * await expect.network().toHaveNoUnhandledRequests()
+         * ```
+         */
+        network(): Assertion<unknown>;
+    }
+}
+export {};

package/dist/matcher-types.js

@@ -0,0 +1 @@
+export {};

package/dist/matchers.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedRequest } from './traffic-registry';
+/**
+ * Waits for the network to settle (two consecutive calm observations,
+ * separated by a poll interval) and returns a single snapshot of the
+ * traffic accumulated up to that point.
+ *
+ * Use it to assert an ABSENCE or an EXACT COUNT, never for the positive,
+ * retrying case (that's `pollTraffic`): it's the basis for the negated
+ * branch of `resolveTraffic` and for `toHaveBeenRequestedTimes`, and
+ * `network.log()` (network.ts) also uses it, outside this file.
+ *
+ * Total budget `QUIESCENCE_TIMEOUT_MS`: if the network doesn't settle in
+ * time, it throws with a dump of what's pending instead of returning a mute
+ * boolean. Full design rationale in the comment block right below the
+ * function.
+ */
+export declare function snapshotAfterIdle(): Promise<ResolvedRequest[]>;

package/dist/matchers.js

@@ -0,0 +1,233 @@
+import { expect } from 'vitest';
+import { noUnhandledRequestsFailureMessage, requestCountFailureMessage, requestFailureMessage, respondedWithFailureMessage, } from './failure-messages';
+import { NETWORK_TARGET } from './network';
+import { matchesBody, matchesSpec } from './spec-matching';
+import { inFlightCount, QUIESCENCE_TIMEOUT_MS, RETRY_INTERVAL_MS, snapshotTraffic, waitForNetworkIdle, } from './traffic-registry';
+// 1s of margin on top of polling every RETRY_INTERVAL_MS: enough for a
+// request fired right after the assert to have time to complete its real
+// trip through the service worker (browser mode, not a same-thread mock).
+const RETRY_TIMEOUT_MS = 1000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// The shorthand `toHaveRespondedWith(500)` and the long form
+// `toHaveRespondedWith({ status: 500 })` coexist in the public signature so
+// the common case doesn't force wrapping an object; normalizing here, once,
+// avoids spreading the `typeof` check across the rest of the matcher.
+function normalizeExpectedResponse(expected) {
+    return typeof expected === 'number' ? { status: expected } : expected;
+}
+/**
+ * Polls `snapshotTraffic()` until an entry matches `spec` and satisfies
+ * `isSatisfyingEntry`, or until `RETRY_TIMEOUT_MS` runs out. Returns the
+ * last traffic seen even if there was never a positive verdict: the
+ * matchers need it to compose the failure message.
+ */
+async function pollTraffic(spec, isSatisfyingEntry) {
+    const deadline = Date.now() + RETRY_TIMEOUT_MS;
+    for (;;) {
+        const traffic = await snapshotTraffic();
+        const pass = traffic.some((entry) => matchesSpec(entry, spec) && isSatisfyingEntry(entry));
+        if (pass || Date.now() >= deadline)
+            return { traffic, pass };
+        await sleep(RETRY_INTERVAL_MS);
+    }
+}
+/**
+ * Waits for the network to settle (two consecutive calm observations,
+ * separated by a poll interval) and returns a single snapshot of the
+ * traffic accumulated up to that point.
+ *
+ * Use it to assert an ABSENCE or an EXACT COUNT, never for the positive,
+ * retrying case (that's `pollTraffic`): it's the basis for the negated
+ * branch of `resolveTraffic` and for `toHaveBeenRequestedTimes`, and
+ * `network.log()` (network.ts) also uses it, outside this file.
+ *
+ * Total budget `QUIESCENCE_TIMEOUT_MS`: if the network doesn't settle in
+ * time, it throws with a dump of what's pending instead of returning a mute
+ * boolean. Full design rationale in the comment block right below the
+ * function.
+ */
+export async function snapshotAfterIdle() {
+    const deadline = performance.now() + QUIESCENCE_TIMEOUT_MS;
+    await sleep(RETRY_INTERVAL_MS);
+    for (;;) {
+        // Second argument: if this sub-call runs out its remaining budget and
+        // throws, the message has to talk about the TOTAL budget, not the
+        // remainder it happened to get (I2 — otherwise the last lap would say
+        // "did not settle within 1ms" after having waited almost the entire
+        // QUIESCENCE_TIMEOUT_MS).
+        await waitForNetworkIdle(Math.max(1, deadline - performance.now()), QUIESCENCE_TIMEOUT_MS);
+        await sleep(RETRY_INTERVAL_MS);
+        if (inFlightCount() === 0)
+            return snapshotTraffic();
+    }
+}
+// Full design and rationale, for whoever reviews this later:
+//
+// Exported (instead of staying private to this file) because network.log()
+// needs the same calm-wait without copying it or calling waitForNetworkIdle
+// raw, which would reopen the blind window this function closes. Any future
+// matcher with the same need (negated forms of toHaveRespondedWith) can call
+// it as-is without needing to export anything else, as long as it lives in
+// this file alongside the rest of the matchers.
+//
+// A single fixed margin before `waitForNetworkIdle` isn't enough: it's a
+// timing assumption measured in this harness (real page-service
+// worker-page round trip of 1 to 6 ms, see
+// docs/knowledge/quiescencia-red-msw.md), not a guarantee. On a loaded CI
+// that round trip can stretch past the margin while the margin's own
+// `setTimeout` keeps its own clock — the calm check would read the registry
+// as empty right when the request is still on its way, precisely in the
+// tests that exist to prove that doesn't happen. That's why a STABILITY
+// CONDITION is required, not a margin: two consecutive observations
+// separated by a poll interval, both calm (`inFlightCount() === 0`). If the
+// second one sees new traffic (arrived during the wait for the first), the
+// calm wait repeats and the check runs again.
+//
+// This does NOT close the blind window: no bounded wait can, that's the
+// preregistered position of docs/knowledge/quiescencia-red-msw.md. It only
+// narrows the practical failure bound from one interval to two — reasoned
+// from how `waitForNetworkIdle` works, not measured: this harness is too
+// fast to reproduce the contended CI that motivates the change. The
+// DETERMINISM tests in matchers-quiescence.test.ts measure something real
+// but different: that the full mechanism (margin + double observation) is
+// needed against a naive check or no wait at all, not that the second
+// observation alone is detectable in this harness (verified by mutation,
+// see docs/knowledge/quiescencia-red-msw.md).
+//
+// The loop needs ONE clock budget for the whole operation, not a fresh one
+// per lap: `waitForNetworkIdle()` with no argument starts its own
+// `QUIESCENCE_TIMEOUT_MS` every time it's called, so a relay of overlapping
+// requests (each one settles the counter just before another starts during
+// the trailing margin) would make the loop never converge or throw — it
+// would die by Vitest's generic timeout, without the dump of what's
+// pending. `deadline` is computed once on entry and each sub-call gets
+// whatever budget is left, never a fresh full one again. If the budget runs
+// out while the counter happens to be at zero, the current sub-call returns
+// right away (nothing to wait for), the check that follows fails if
+// something started meanwhile, and the next sub-call gets ~1 ms: if
+// something is in flight, its own loop detects it once that remainder
+// passes and throws with the dump — bounded to, at most, one extra
+// `RETRY_INTERVAL_MS` on top of the global budget, never unbounded.
+/**
+ * Single decision point between retrying and waiting for calm. `.not`
+ * needs quiescence: retrying until something shows up, applied to an
+ * absence, would give a false positive with any request still in flight
+ * (the DETERMINISM test in matchers-quiescence.test.ts catches exactly
+ * that). The positive case keeps the retrying poll because there it's the
+ * request arriving that matters, not the whole network going quiet.
+ */
+async function resolveTraffic(spec, isSatisfyingEntry, isNot) {
+    if (!isNot)
+        return pollTraffic(spec, isSatisfyingEntry);
+    const traffic = await snapshotAfterIdle();
+    return {
+        traffic,
+        pass: traffic.some((entry) => matchesSpec(entry, spec) && isSatisfyingEntry(entry)),
+    };
+}
+expect.extend({
+    async toHaveBeenRequested(spec) {
+        const { traffic, pass } = await resolveTraffic(spec, () => true, this.isNot);
+        return {
+            pass,
+            message: () => requestFailureMessage({
+                utils: this.utils,
+                matcherName: 'toHaveBeenRequested',
+                spec,
+                traffic,
+                isNot: this.isNot,
+            }),
+        };
+    },
+    async toHaveBeenIntercepted(spec) {
+        // Neither passthrough (matched without mocked) nor the 500 MSW
+        // fabricates in error mode (mocked without matched) count as
+        // intercepted: the handler itself has to have responded. See
+        // docs/knowledge/msw-browser-mode.md.
+        const { traffic, pass } = await resolveTraffic(spec, (entry) => entry.matched && entry.mocked, this.isNot);
+        return {
+            pass,
+            message: () => requestFailureMessage({
+                utils: this.utils,
+                matcherName: 'toHaveBeenIntercepted',
+                spec,
+                traffic,
+                isNot: this.isNot,
+            }),
+        };
+    },
+    async toHaveRespondedWith(spec, expected) {
+        const expectedResponse = normalizeExpectedResponse(expected);
+        // The above (intercepted: neither passthrough nor an MSW-fabricated
+        // error, see toHaveBeenIntercepted above), plus this response: exact
+        // status plus, if given, a subset of the response body using the same
+        // rules matchesSpec applies to the request.
+        const isSatisfyingEntry = (entry) => entry.matched &&
+            entry.mocked &&
+            entry.status === expectedResponse.status &&
+            (expectedResponse.body === undefined ||
+                matchesBody(entry.responseBody, expectedResponse.body, expectedResponse.exact));
+        const { traffic, pass } = await resolveTraffic(spec, isSatisfyingEntry, this.isNot);
+        return {
+            pass,
+            message: () => respondedWithFailureMessage({
+                utils: this.utils,
+                spec,
+                expected: expectedResponse,
+                traffic,
+                isNot: this.isNot,
+            }),
+        };
+    },
+    async toHaveBeenRequestedTimes(spec, count) {
+        // Always waits for calm, negated with `.not` or not: an exact count
+        // taken mid-traffic is as false as an absence taken mid-traffic (the
+        // other DETERMINISM test in the same test file).
+        const traffic = await snapshotAfterIdle();
+        const matchingEntries = traffic.filter((entry) => matchesSpec(entry, spec));
+        const foundCount = matchingEntries.length;
+        return {
+            pass: foundCount === count,
+            message: () => requestCountFailureMessage({
+                utils: this.utils,
+                spec,
+                expectedCount: count,
+                foundCount,
+                traffic,
+                isNot: this.isNot,
+            }),
+        };
+    },
+    async toHaveNoUnhandledRequests(received) {
+        // This matcher doesn't describe a request: it hangs off
+        // `expect.network()`, the only place that produces the
+        // `NETWORK_TARGET` marker. Used on anything else (a `get(...)`
+        // descriptor, a string) is a usage error, not an assertion failing on
+        // data.
+        if (received !== NETWORK_TARGET) {
+            return {
+                pass: false,
+                message: () => 'toHaveNoUnhandledRequests is used through expect.network(), not on a request descriptor: expect.network().toHaveNoUnhandledRequests()',
+            };
+        }
+        const traffic = await snapshotAfterIdle();
+        const unhandledEntries = traffic.filter((entry) => entry.unhandled);
+        return {
+            pass: unhandledEntries.length === 0,
+            message: () => noUnhandledRequestsFailureMessage({
+                utils: this.utils,
+                unhandledEntries,
+                traffic,
+                isNot: this.isNot,
+            }),
+        };
+    },
+});
+// Vitest doesn't allow declaring new properties on `ExpectStatic` via
+// `expect.extend`: `expect.extend` only installs matchers inside an
+// `Assertion`. `expect.network()` needs to be a top-level function on
+// `expect` itself, so it's assigned directly; the type shape comes from the
+// `ExpectStatic` augmentation in matcher-types.ts.
+expect.network = () => expect(NETWORK_TARGET);

package/dist/mount.d.ts

@@ -0,0 +1,45 @@
+import type { ReactElement } from 'react';
+import type { RequestHandler } from 'msw';
+import { type RenderResult } from 'vitest-browser-react';
+/** Options for {@link mount}. Both are optional: `mount(<App />)` alone just mounts. */
+export interface MountOptions {
+    /**
+     * Same-origin URI starting with `/`, query and hash included (for example
+     * `/products?filter=bread#detail`). Applied with `history.pushState`
+     * before render so the application's router reads it on mount.
+     */
+    path?: string;
+    /**
+     * MSW handlers of this test's own. Installed with `worker.use()` before
+     * render, so they take priority over the suite's for the same route, and
+     * `setupNetwork()` undoes them in its `afterEach`.
+     */
+    network?: RequestHandler[];
+}
+/**
+ * Mounts `ui` with `vitest-browser-react`, optionally on a real document
+ * route and with test-specific MSW handlers.
+ *
+ * `path`, if given, has to be a same-origin URI starting with `/`: it's
+ * applied with `history.pushState` BEFORE render because the application's
+ * `BrowserRouter` reads the URL on mount and only listens to `popstate`
+ * afterwards (measured — see
+ * `.claude/docs/references/measured-foundations.md`). The URI can carry
+ * query and hash: they flow through the router the same as the path.
+ * `setupNetwork()` restores the original URL in its `afterEach`, so every
+ * test starts from the same route regardless of what the previous one
+ * mounted.
+ *
+ * `network`, if given, is registered with `worker.use()` before render: its
+ * handlers take priority over the suite's for this request, with the same
+ * resolution rules as MSW.
+ *
+ * @example
+ * ```tsx
+ * import { mount } from '@yabbadabbadev/pepito'
+ *
+ * const screen = await mount(<App />, { path: '/products?filter=bread' })
+ * await expect.element(screen.getByText('filter: bread')).toBeVisible()
+ * ```
+ */
+export declare function mount(ui: ReactElement, options?: MountOptions): Promise<RenderResult>;

package/dist/mount.js

@@ -0,0 +1,61 @@
+import { render } from 'vitest-browser-react';
+import { requireNetworkContext } from './network-singleton';
+// The '/' prefix alone isn't enough: '//evil.com' is protocol-relative and
+// WHATWG also treats '/\' as introducing an authority, so both would pass
+// it and pushState would be the one throwing the raw SecurityError further
+// down.
+function isSameOriginPath(path) {
+    if (!path.startsWith('/'))
+        return false;
+    try {
+        return new URL(path, location.origin).origin === location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Mounts `ui` with `vitest-browser-react`, optionally on a real document
+ * route and with test-specific MSW handlers.
+ *
+ * `path`, if given, has to be a same-origin URI starting with `/`: it's
+ * applied with `history.pushState` BEFORE render because the application's
+ * `BrowserRouter` reads the URL on mount and only listens to `popstate`
+ * afterwards (measured — see
+ * `.claude/docs/references/measured-foundations.md`). The URI can carry
+ * query and hash: they flow through the router the same as the path.
+ * `setupNetwork()` restores the original URL in its `afterEach`, so every
+ * test starts from the same route regardless of what the previous one
+ * mounted.
+ *
+ * `network`, if given, is registered with `worker.use()` before render: its
+ * handlers take priority over the suite's for this request, with the same
+ * resolution rules as MSW.
+ *
+ * @example
+ * ```tsx
+ * import { mount } from '@yabbadabbadev/pepito'
+ *
+ * const screen = await mount(<App />, { path: '/products?filter=bread' })
+ * await expect.element(screen.getByText('filter: bread')).toBeVisible()
+ * ```
+ */
+export async function mount(ui, options = {}) {
+    const { worker } = requireNetworkContext('mount');
+    const { path, network: testHandlers } = options;
+    if (path !== undefined && !isSameOriginPath(path)) {
+        throw new Error(`pepito: path must be a same-origin URI that starts with '/'; ` +
+            `received: ${path}. A different origin is mocked in the MSW ` +
+            `handlers, not in the mount.`);
+    }
+    // Before render: the app's router reads the URL on mount and only
+    // listens to popstate afterwards. See
+    // docs/knowledge/url-navegacion-browser-mode.md.
+    if (path !== undefined) {
+        history.pushState({}, '', path);
+    }
+    if (testHandlers !== undefined && testHandlers.length > 0) {
+        worker.use(...testHandlers);
+    }
+    return render(ui);
+}

package/dist/msw-events.d.ts

@@ -0,0 +1,6 @@
+import type { SetupWorker } from 'msw/browser';
+/**
+ * Hooks up the traffic registry (traffic-registry.ts) to MSW's events.
+ * `setupNetwork()` calls it once per worker, before `worker.start()`.
+ */
+export declare function watchNetwork(events: SetupWorker['events']): void;