@clipboard-health/playwright-toolkit 1.3.2 → 1.3.3

package/README.md

@@ -2,7 +2,7 @@
 
 Shared anti-flake primitives for Clipboard Health Playwright suites.
 
-The package owns retry policy, APM correlation, shared admin-token caching, deployed-asset checks, Mailpit polling, Cognito login diagnostics, and setup retry classification. Consuming repositories keep only configuration and domain-specific matching.
+The package owns retry policy, APM correlation, shared admin-token caching, deployed-asset checks, JSON response lifetime capture, Mailpit polling, Cognito login diagnostics, and setup retry classification. Consuming repositories keep only configuration and domain-specific matching.
 
 ## Install
 
@@ -21,6 +21,7 @@ npm install --save-dev @clipboard-health/playwright-toolkit
 | Copy-pasted traceparent page fixture    | `createTraceparentFixtures()`                                                            |
 | Admin token promise cache and file lock | `generateAdminAuthToken()` or `getOrCreateAdminAuthToken()`                              |
 | Deployed frontend/mobile asset loops    | `verifyDeployedAssets()` and `waitForDeployedAssets()`                                   |
+| Deferred Playwright JSON response reads | `waitForParsedJsonResponse()`                                                            |
 | Mailpit search/fetch loops              | `createMailpitClient()`, `fetchMagicLinkFromMailpit()`, `fetchEmailOtpCodeFromMailpit()` |
 | Cognito OTP redirect debugging          | `fillOtpAndWaitForCognitoRedirect()`                                                     |
 | Setup HTTP and identity retry checks    | `classifySetupRetry()` and `isRetryableHttpStatus()`                                     |
@@ -87,6 +88,31 @@ operation: async ({ signal }) =>
   });
 ```
 
+## JSON response lifetime
+
+Playwright response bodies can become unreadable after a document navigation. Use
+`waitForParsedJsonResponse` when a page action both waits for a JSON response and crosses a
+navigation boundary. The helper parses each candidate inside the `waitForResponse` predicate and
+returns only the parsed value, so callers cannot accidentally retain a lazy `Response` handle.
+
+```typescript
+const workerResponsePromise = waitForParsedJsonResponse({
+  page,
+  timeoutMs: 30_000,
+  isCandidate: ({ response }) =>
+    response.ok() && new URL(response.url()).pathname === "/api/worker",
+  parseCandidate: ({ body }) => workerResponseSchema.parse(body),
+});
+
+await page.reload({ waitUntil: "domcontentloaded" });
+
+const workerResponse = await workerResponsePromise;
+```
+
+Return `undefined` from `parseCandidate` when the URL-level candidate is valid but its body is not
+the response the test needs. Parsing errors propagate immediately. Keep repository-specific URL,
+method, resource-type, and schema matching in the consumer.
+
 ## Per-test traceparent fixture
 
 Extend the repository's existing Playwright test object once:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/playwright-toolkit",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Shared anti-flake primitives for Clipboard Health Playwright suites.",
   "keywords": [
     "cognito",

package/src/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./lib/adminAuthToken";
 export * from "./lib/cognitoDiagnostics";
 export * from "./lib/deployedAssets";
+export * from "./lib/jsonResponse";
 export * from "./lib/mailpit";
 export * from "./lib/retry";
 export * from "./lib/setupRetry";

package/src/index.js

@@ -4,6 +4,7 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/adminAuthToken"), exports);
 tslib_1.__exportStar(require("./lib/cognitoDiagnostics"), exports);
 tslib_1.__exportStar(require("./lib/deployedAssets"), exports);
+tslib_1.__exportStar(require("./lib/jsonResponse"), exports);
 tslib_1.__exportStar(require("./lib/mailpit"), exports);
 tslib_1.__exportStar(require("./lib/retry"), exports);
 tslib_1.__exportStar(require("./lib/setupRetry"), exports);

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/playwright-toolkit/src/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,mEAAyC;AACzC,+DAAqC;AACrC,wDAA8B;AAC9B,sDAA4B;AAC5B,2DAAiC;AACjC,4DAAkC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/playwright-toolkit/src/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,mEAAyC;AACzC,+DAAqC;AACrC,6DAAmC;AACnC,wDAA8B;AAC9B,sDAA4B;AAC5B,2DAAiC;AACjC,4DAAkC"}

package/src/lib/jsonResponse.d.ts

@@ -0,0 +1,18 @@
+import type { Page, Response } from "@playwright/test";
+export interface WaitForParsedJsonResponseParams<T> {
+    isCandidate: (params: {
+        response: Response;
+    }) => boolean;
+    page: Page;
+    parseCandidate: (params: {
+        body: unknown;
+        response: Response;
+    }) => T | undefined;
+    timeoutMs: number;
+}
+/**
+ * Waits for a matching JSON response and parses its body while Playwright's
+ * document-scoped response resource is still readable. Return `undefined`
+ * from `parseCandidate` to keep waiting for another candidate response.
+ */
+export declare function waitForParsedJsonResponse<T>(params: WaitForParsedJsonResponseParams<T>): Promise<T>;

package/src/lib/jsonResponse.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForParsedJsonResponse = waitForParsedJsonResponse;
+const util_ts_1 = require("@clipboard-health/util-ts");
+/**
+ * Waits for a matching JSON response and parses its body while Playwright's
+ * document-scoped response resource is still readable. Return `undefined`
+ * from `parseCandidate` to keep waiting for another candidate response.
+ */
+async function waitForParsedJsonResponse(params) {
+    const { isCandidate, page, parseCandidate, timeoutMs } = params;
+    const parsedCandidates = new WeakMap();
+    const response = await page.waitForResponse(async (candidateResponse) => {
+        if (!isCandidate({ response: candidateResponse })) {
+            return false;
+        }
+        const parsedCandidate = parseCandidate({
+            body: await candidateResponse.json(),
+            response: candidateResponse,
+        });
+        // JSON null is a valid parsed value; only undefined means "keep waiting".
+        if (parsedCandidate === undefined) {
+            return false;
+        }
+        parsedCandidates.set(candidateResponse, { value: parsedCandidate });
+        return true;
+    }, { timeout: timeoutMs });
+    const parsedResponse = parsedCandidates.get(response);
+    if (!(0, util_ts_1.isDefined)(parsedResponse)) {
+        throw new Error("Expected the matched JSON response body to be captured while it was readable.");
+    }
+    return parsedResponse.value;
+}
+//# sourceMappingURL=jsonResponse.js.map

package/src/lib/jsonResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonResponse.js","sourceRoot":"","sources":["../../../../../packages/playwright-toolkit/src/lib/jsonResponse.ts"],"names":[],"mappings":";;;AAAA,uDAAsD;AActD;;;;GAIG;AACI,KAAK,oCACV,MAA0C;IAE1C,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAChE,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAgC,CAAC;IAErE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CACzC,KAAK,EAAE,iBAAiB,EAAE,EAAE;QAC1B,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;YAClD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,eAAe,GAAG,cAAc,CAAC;YACrC,IAAI,EAAE,MAAM,iBAAiB,CAAC,IAAI,EAAE;YACpC,QAAQ,EAAE,iBAAiB;SAC5B,CAAC,CAAC;QACH,0EAA0E;QAC1E,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,gBAAgB,CAAC,GAAG,CAAC,iBAAiB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC,EACD,EAAE,OAAO,EAAE,SAAS,EAAE,CACvB,CAAC;IACF,MAAM,cAAc,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEtD,IAAI,CAAC,IAAA,mBAAS,EAAC,cAAc,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAC,KAAK,CAAC;AAC9B,CAAC"}