@yabbadabbadev/pepito 0.1.0

package/dist/traffic-registry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Traffic entry as it lives in the registry while the test runs: `body` and
+ * `responseBody` are promises because they can only be read once (measured
+ * — see `.claude/docs/references/measured-foundations.md`) and are stored
+ * without awaiting, so as not to block the `request:start` listener that
+ * opens them.
+ */
+export interface ObservedRequest {
+    requestId: string;
+    method: string;
+    origin: string;
+    path: string;
+    searchParams: Record<string, string>;
+    body: Promise<unknown>;
+    matched: boolean;
+    mocked: boolean;
+    bypassed: boolean;
+    unhandled: boolean;
+    status: number | null;
+    responseBody: Promise<unknown>;
+}
+/** Same shape as {@link ObservedRequest} with `body` and `responseBody` already resolved: what the matchers and failure messages see. */
+export interface ResolvedRequest extends Omit<ObservedRequest, 'body' | 'responseBody'> {
+    body: unknown;
+    responseBody: unknown;
+}
+/**
+ * Opens a traffic entry with what can only be read at `request:start`
+ * (measured — see `.claude/docs/references/measured-foundations.md`) and
+ * marks it in flight.
+ * `watchNetwork` (msw-events.ts) is the only caller.
+ */
+export declare function recordRequestStart(requestId: string, startFields: Pick<ObservedRequest, 'method' | 'origin' | 'path' | 'searchParams' | 'body'>): void;
+/**
+ * Marks that a handler matched the route. By itself it doesn't imply it
+ * responded — a `passthrough()` also emits this event — which is why
+ * `toHaveBeenIntercepted` (matchers.ts) additionally requires
+ * {@link recordMockedResponse}.
+ */
+export declare function recordMatch(requestId: string): void;
+/** Records the response a handler produced and closes the request (removes it from `pending`). */
+export declare function recordMockedResponse(requestId: string, status: number, responseBody: Promise<unknown>): void;
+/** Records that the request went out to the real network (passthrough or no handler) and closes the request. */
+export declare function recordBypassResponse(requestId: string, status: number): void;
+/** Marks a request as unhandled; this is what the `toHaveNoUnhandledRequests` guardrail reads. */
+export declare function recordUnhandled(requestId: string): void;
+/**
+ * Resolves the pending `body`/`responseBody` promises and returns a
+ * snapshot of the traffic accumulated so far. Doesn't empty the registry:
+ * several calls within the same test see the same history plus whatever is
+ * new.
+ */
+export declare function snapshotTraffic(): Promise<ResolvedRequest[]>;
+/** Empties the registry and the in-flight counter; called by `setupNetwork()` in its `afterEach`. */
+export declare function resetTraffic(): void;
+/** Number of requests with no close event yet. See {@link waitForNetworkIdle}. */
+export declare function inFlightCount(): number;
+/** Poll interval for `waitForNetworkIdle`; also used by the retrying matchers. */
+export declare const RETRY_INTERVAL_MS = 25;
+/** Default budget for {@link waitForNetworkIdle} before it throws with a dump of what's pending. */
+export declare const QUIESCENCE_TIMEOUT_MS = 4000;
+/**
+ * Waits for the in-flight request counter to reach zero.
+ *
+ * Polls instead of reacting to an event because the close of the last
+ * request can arrive before any waiting listener gets installed. If the
+ * timeout runs out, it throws with a dump of what's pending instead of
+ * returning a boolean: an aborted request whose handler never finishes
+ * would leave the counter stuck forever, and a meter that cannot measure
+ * has to go red with diagnostics, not stay silent.
+ *
+ * A single call isn't enough to know "there's no traffic": a request fired
+ * in the same tick as the call hasn't yet crossed the real round trip to
+ * the service worker that registers its `request:start`, so this function
+ * reads the counter at zero by construction, not by actual absence (see
+ * `.claude/docs/references/measured-foundations.md`). Whoever needs to
+ * assert an absence or count with precision must go through
+ * `snapshotAfterIdle` in `pepito/src/matchers.ts`, which closes that window
+ * with a two-observation stability condition; calling this function
+ * directly reopens it.
+ *
+ * @param timeoutMs - The real budget for this call: what governs when it throws.
+ * @param reportedTimeoutMs - The number that appears in the error message if it
+ * throws; defaults to the same `timeoutMs`. Exists because `snapshotAfterIdle`
+ * splits ONE global budget across several sub-calls (each with whatever is
+ * left of the total, never a fresh full one) and needs the final message to
+ * talk about that total, not the remaining milliseconds the last sub-call
+ * got — otherwise the last lap of the loop could report "did not settle
+ * within 1ms" after having waited the entire budget.
+ */
+export declare function waitForNetworkIdle(timeoutMs?: number, reportedTimeoutMs?: number): Promise<void>;

package/dist/traffic-registry.js

@@ -0,0 +1,131 @@
+const traffic = new Map();
+// A Set of in-flight requestId, not an integer: a close event with no prior
+// request:start (traffic from before a resetTraffic) is simply ignored,
+// instead of leaving a counter stuck negative without anyone noticing.
+// Measured in docs/knowledge/quiescencia-red-msw.md.
+const pending = new Set();
+/**
+ * Opens a traffic entry with what can only be read at `request:start`
+ * (measured — see `.claude/docs/references/measured-foundations.md`) and
+ * marks it in flight.
+ * `watchNetwork` (msw-events.ts) is the only caller.
+ */
+export function recordRequestStart(requestId, startFields) {
+    traffic.set(requestId, {
+        requestId,
+        ...startFields,
+        matched: false,
+        mocked: false,
+        bypassed: false,
+        unhandled: false,
+        status: null,
+        responseBody: Promise.resolve(undefined),
+    });
+    pending.add(requestId);
+}
+/**
+ * Marks that a handler matched the route. By itself it doesn't imply it
+ * responded — a `passthrough()` also emits this event — which is why
+ * `toHaveBeenIntercepted` (matchers.ts) additionally requires
+ * {@link recordMockedResponse}.
+ */
+export function recordMatch(requestId) {
+    const entry = traffic.get(requestId);
+    if (entry)
+        entry.matched = true;
+}
+/** Records the response a handler produced and closes the request (removes it from `pending`). */
+export function recordMockedResponse(requestId, status, responseBody) {
+    const entry = traffic.get(requestId);
+    if (entry) {
+        entry.mocked = true;
+        entry.status = status;
+        entry.responseBody = responseBody;
+    }
+    pending.delete(requestId);
+}
+/** Records that the request went out to the real network (passthrough or no handler) and closes the request. */
+export function recordBypassResponse(requestId, status) {
+    const entry = traffic.get(requestId);
+    if (entry) {
+        entry.bypassed = true;
+        entry.status = status;
+    }
+    pending.delete(requestId);
+}
+/** Marks a request as unhandled; this is what the `toHaveNoUnhandledRequests` guardrail reads. */
+export function recordUnhandled(requestId) {
+    const entry = traffic.get(requestId);
+    if (entry)
+        entry.unhandled = true;
+}
+/**
+ * Resolves the pending `body`/`responseBody` promises and returns a
+ * snapshot of the traffic accumulated so far. Doesn't empty the registry:
+ * several calls within the same test see the same history plus whatever is
+ * new.
+ */
+export async function snapshotTraffic() {
+    return Promise.all([...traffic.values()].map(async (entry) => ({
+        ...entry,
+        body: await entry.body,
+        responseBody: await entry.responseBody,
+    })));
+}
+/** Empties the registry and the in-flight counter; called by `setupNetwork()` in its `afterEach`. */
+export function resetTraffic() {
+    traffic.clear();
+    pending.clear();
+}
+/** Number of requests with no close event yet. See {@link waitForNetworkIdle}. */
+export function inFlightCount() {
+    return pending.size;
+}
+/** Poll interval for `waitForNetworkIdle`; also used by the retrying matchers. */
+export const RETRY_INTERVAL_MS = 25;
+/** Default budget for {@link waitForNetworkIdle} before it throws with a dump of what's pending. */
+export const QUIESCENCE_TIMEOUT_MS = 4000;
+/**
+ * Waits for the in-flight request counter to reach zero.
+ *
+ * Polls instead of reacting to an event because the close of the last
+ * request can arrive before any waiting listener gets installed. If the
+ * timeout runs out, it throws with a dump of what's pending instead of
+ * returning a boolean: an aborted request whose handler never finishes
+ * would leave the counter stuck forever, and a meter that cannot measure
+ * has to go red with diagnostics, not stay silent.
+ *
+ * A single call isn't enough to know "there's no traffic": a request fired
+ * in the same tick as the call hasn't yet crossed the real round trip to
+ * the service worker that registers its `request:start`, so this function
+ * reads the counter at zero by construction, not by actual absence (see
+ * `.claude/docs/references/measured-foundations.md`). Whoever needs to
+ * assert an absence or count with precision must go through
+ * `snapshotAfterIdle` in `pepito/src/matchers.ts`, which closes that window
+ * with a two-observation stability condition; calling this function
+ * directly reopens it.
+ *
+ * @param timeoutMs - The real budget for this call: what governs when it throws.
+ * @param reportedTimeoutMs - The number that appears in the error message if it
+ * throws; defaults to the same `timeoutMs`. Exists because `snapshotAfterIdle`
+ * splits ONE global budget across several sub-calls (each with whatever is
+ * left of the total, never a fresh full one) and needs the final message to
+ * talk about that total, not the remaining milliseconds the last sub-call
+ * got — otherwise the last lap of the loop could report "did not settle
+ * within 1ms" after having waited the entire budget.
+ */
+export async function waitForNetworkIdle(timeoutMs = QUIESCENCE_TIMEOUT_MS, reportedTimeoutMs = timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (pending.size > 0) {
+        if (Date.now() >= deadline) {
+            const dump = [...pending]
+                .map((requestId) => {
+                const entry = traffic.get(requestId);
+                return entry ? `${entry.method} ${entry.path}` : requestId;
+            })
+                .join('\n  ');
+            throw new Error(`the network did not settle within ${reportedTimeoutMs}ms; in flight:\n  ${dump}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+    }
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@yabbadabbadev/pepito",
+  "version": "0.1.0",
+  "description": "Network test utilities for Vitest browser mode: application mounting and matchers over the traffic observed by MSW",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yabbadabbadev/pepito.git"
+  },
+  "homepage": "https://github.com/yabbadabbadev/pepito",
+  "bugs": {
+    "url": "https://github.com/yabbadabbadev/pepito/issues"
+  },
+  "keywords": [
+    "vitest",
+    "browser-mode",
+    "msw",
+    "testing",
+    "network",
+    "matchers"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:verbose": "vitest run --reporter=verbose",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "pack:local": "npm run build && npm pack --pack-destination dist-pack",
+    "setup": "playwright install chromium",
+    "lint": "eslint --cache . --report-unused-disable-directives --max-warnings 0",
+    "lint-fix": "eslint --cache . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "peerDependencies": {
+    "msw": "^2.15.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vitest": "^4.0.0",
+    "vitest-browser-react": "^2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "@vitejs/plugin-react": "^6.0.5",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.26",
+    "eslint-plugin-vitest-globals": "^1.6.1",
+    "globals": "^17.9.0",
+    "msw": "^2.15.0",
+    "playwright": "^1.62.1",
+    "prettier": "^3.9.6",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router": "^8.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "vitest-browser-react": "^2.2.0"
+  },
+  "msw": {
+    "workerDirectory": [
+      "public"
+    ]
+  }
+}