@rvoh/psychic-spec-helpers 3.0.0 → 3.1.0

package/dist/esm/src/feature/helpers/resetBrowserState.js

@@ -0,0 +1,62 @@
+async function bestEffort(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        // Per-spec teardown must never throw: a failure cleaning one spec's state
+        // would fail an unrelated spec's `afterEach`. Swallow and move on.
+        void err;
+    }
+}
+/**
+ * Per-spec browser cleanup for feature specs that share a single browser
+ * across spec files. Call in `afterEach` so every spec starts from a clean
+ * slate and so server-side resources are released between specs.
+ *
+ * Three best-effort steps, in this order:
+ *
+ *  1. Clear `localStorage` / `sessionStorage` for the current origin (auth
+ *     tokens, app state). Done first, while the page is still on the app
+ *     origin — storage is inaccessible once we navigate to `about:blank`.
+ *  2. Clear cookies for the page's browser context (context-scoped so
+ *     parallel contexts stay isolated).
+ *  3. Navigate to `about:blank`. Besides the clean slate, this cancels any
+ *     still-in-flight requests, releasing server-side resources they held
+ *     (e.g. a pooled database client) so server teardown isn't blocked.
+ *
+ * The shared browser is intentionally left open and reusable. Operates on
+ * the global `page`; a no-op if there is no open page.
+ */
+export default async function resetBrowserState() {
+    const page = globalThis.page;
+    if (!page || page.isClosed())
+        return;
+    if (/^https?:/.test(page.url())) {
+        await bestEffort(() => page.evaluate(() => {
+            localStorage.clear();
+            sessionStorage.clear();
+            // `document` isn't in the Node lib this package is type-checked
+            // against (localStorage/sessionStorage are), so reach it through a
+            // typed globalThis cast — it exists at runtime in the browser.
+            const { document } = globalThis;
+            // Expire every JS-visible cookie on this origin. The browser-context
+            // cookie API below covers HttpOnly cookies, but does not reliably
+            // surface document.cookie-set cookies across every Puppeteer browser
+            // backend (notably Firefox/WebDriver-BiDi), so sweep here too.
+            for (const entry of document.cookie.split(';')) {
+                const eq = entry.indexOf('=');
+                const name = (eq > -1 ? entry.slice(0, eq) : entry).trim();
+                if (name)
+                    document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`;
+            }
+        }));
+    }
+    // Catches HttpOnly cookies (and any the JS sweep above could not reach).
+    await bestEffort(async () => {
+        const context = page.browserContext();
+        const cookies = await context.cookies();
+        if (cookies.length)
+            await context.deleteCookie(...cookies);
+    });
+    await bestEffort(() => page.goto('about:blank'));
+}

package/dist/esm/src/index.js

@@ -9,5 +9,6 @@ export { default as launchBrowser } from './feature/helpers/launchBrowser.js';
 export { default as launchDevServer, stopDevServer, stopDevServers, } from './feature/helpers/launchDevServer.js';
 export { default as launchPage } from './feature/helpers/launchPage.js';
 export { default as providePuppeteerViteMatchers } from './feature/helpers/providePuppeteerViteMatchers.js';
+export { default as resetBrowserState } from './feature/helpers/resetBrowserState.js';
 export { default as visit } from './feature/helpers/visit.js';
 export default {};

package/dist/types/src/feature/helpers/resetBrowserState.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-spec browser cleanup for feature specs that share a single browser
+ * across spec files. Call in `afterEach` so every spec starts from a clean
+ * slate and so server-side resources are released between specs.
+ *
+ * Three best-effort steps, in this order:
+ *
+ *  1. Clear `localStorage` / `sessionStorage` for the current origin (auth
+ *     tokens, app state). Done first, while the page is still on the app
+ *     origin — storage is inaccessible once we navigate to `about:blank`.
+ *  2. Clear cookies for the page's browser context (context-scoped so
+ *     parallel contexts stay isolated).
+ *  3. Navigate to `about:blank`. Besides the clean slate, this cancels any
+ *     still-in-flight requests, releasing server-side resources they held
+ *     (e.g. a pooled database client) so server teardown isn't blocked.
+ *
+ * The shared browser is intentionally left open and reusable. Operates on
+ * the global `page`; a no-op if there is no open page.
+ */
+export default function resetBrowserState(): Promise<void>;

package/dist/types/src/index.d.ts

@@ -13,6 +13,7 @@ export { default as launchBrowser } from './feature/helpers/launchBrowser.js';
 export { default as launchDevServer, stopDevServer, stopDevServers, } from './feature/helpers/launchDevServer.js';
 export { default as launchPage } from './feature/helpers/launchPage.js';
 export { default as providePuppeteerViteMatchers } from './feature/helpers/providePuppeteerViteMatchers.js';
+export { default as resetBrowserState } from './feature/helpers/resetBrowserState.js';
 export { default as visit } from './feature/helpers/visit.js';
 declare global {
     const context: (typeof import('vitest'))['describe'];

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@rvoh/psychic-spec-helpers",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "psychic framework spec helpers",
   "author": "RVO Health",
   "repository": {
@@ -29,24 +29,17 @@
     "psy": "NODE_ENV=${NODE_ENV:-test} tsx test-app/src/cli/index.ts",
     "uspec": "vitest --config ./spec/unit/vite.config.ts",
     "fspec": "vitest --config ./spec/features/vite.config.ts",
-    "build": "echo \"building psychic-spec-helpers...\" && rm -rf dist && npx tsc -p ./tsconfig.esm.build.json",
-    "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && npx tsc -p ./tsconfig.esm.build.test-app.json && echo \"building test app to cjs...\" && npx tsc -p ./tsconfig.cjs.build.test-app.json",
+    "build": "echo \"building psychic-spec-helpers...\" && rm -rf dist && tsc -p ./tsconfig.esm.build.json",
+    "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && tsc -p ./tsconfig.esm.build.test-app.json && echo \"building test app to cjs...\" && npx tsc -p ./tsconfig.cjs.build.test-app.json",
     "lint": "pnpm eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\" && pnpm prettier . --check",
     "format": "pnpm prettier . --write",
     "prepack": "pnpm build"
   },
-  "pnpm": {
-    "overrides": {
-      "minimatch@3.1.2": "3.1.3",
-      "minimatch@5.1.6": "5.1.7",
-      "minimatch@9.0.5": "9.0.6"
-    }
-  },
   "peerDependencies": {
     "@rvoh/dream": "*",
     "@types/node": "*",
     "@types/supertest": "*",
-    "puppeteer": "*",
+    "puppeteer": ">=24.15.0",
     "supertest": "*",
     "typescript": "*"
   },
@@ -55,31 +48,31 @@
     "@koa/cors": "^5.0.0",
     "@koa/etag": "^5.0.2",
     "@koa/router": "^15.3.0",
-    "@rvoh/dream": "^2.1.1",
+    "@rvoh/dream": "^2.5.7",
     "@rvoh/dream-spec-helpers": "^2.0.0",
-    "@rvoh/psychic": "^3.0.0-alpha.4",
+    "@rvoh/psychic": "^3.0.5",
     "@types/cookiejar": "^2",
     "@types/node": "^22.5.1",
     "@types/pg": "^8",
     "@types/supertest": "^6.0.3",
-    "@typescript-eslint/parser": "^8.48.1",
-    "eslint": "^9.39.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "eslint": "^9.39.4",
     "globals": "^16.5.0",
     "koa-bodyparser": "^4.4.1",
     "koa-conditional-get": "^3.0.0",
-    "kysely": "^0.28.5",
+    "kysely": "^0.28.14",
     "kysely-codegen": "~0.19.0",
     "luxon-jest-matchers": "^0.1.14",
     "openapi-typescript": "^7.10.1",
     "pg": "^8.13.1",
     "prettier": "^3.5.3",
-    "puppeteer": "^24.25.0",
-    "supertest": "^7.1.4",
+    "puppeteer": "^24.39.1",
+    "supertest": "^7.2.2",
     "ts-node": "^10.9.2",
     "tsx": "^4.20.6",
     "typescript": "^5.5.4",
-    "typescript-eslint": "^8.48.1",
-    "vitest": "^4.0.10"
+    "typescript-eslint": "^8.57.1",
+    "vitest": "^4.1.0"
   },
   "dependencies": {
     "commander": "^14.0.2",

package/src/feature/helpers/resetBrowserState.ts

@@ -0,0 +1,66 @@
+import { Page } from 'puppeteer'
+
+async function bestEffort(fn: () => Promise<unknown>): Promise<void> {
+  try {
+    await fn()
+  } catch (err) {
+    // Per-spec teardown must never throw: a failure cleaning one spec's state
+    // would fail an unrelated spec's `afterEach`. Swallow and move on.
+    void err
+  }
+}
+
+/**
+ * Per-spec browser cleanup for feature specs that share a single browser
+ * across spec files. Call in `afterEach` so every spec starts from a clean
+ * slate and so server-side resources are released between specs.
+ *
+ * Three best-effort steps, in this order:
+ *
+ *  1. Clear `localStorage` / `sessionStorage` for the current origin (auth
+ *     tokens, app state). Done first, while the page is still on the app
+ *     origin — storage is inaccessible once we navigate to `about:blank`.
+ *  2. Clear cookies for the page's browser context (context-scoped so
+ *     parallel contexts stay isolated).
+ *  3. Navigate to `about:blank`. Besides the clean slate, this cancels any
+ *     still-in-flight requests, releasing server-side resources they held
+ *     (e.g. a pooled database client) so server teardown isn't blocked.
+ *
+ * The shared browser is intentionally left open and reusable. Operates on
+ * the global `page`; a no-op if there is no open page.
+ */
+export default async function resetBrowserState(): Promise<void> {
+  const page = (globalThis as { page?: Page }).page
+  if (!page || page.isClosed()) return
+
+  if (/^https?:/.test(page.url())) {
+    await bestEffort(() =>
+      page.evaluate(() => {
+        localStorage.clear()
+        sessionStorage.clear()
+        // `document` isn't in the Node lib this package is type-checked
+        // against (localStorage/sessionStorage are), so reach it through a
+        // typed globalThis cast — it exists at runtime in the browser.
+        const { document } = globalThis as unknown as { document: { cookie: string } }
+        // Expire every JS-visible cookie on this origin. The browser-context
+        // cookie API below covers HttpOnly cookies, but does not reliably
+        // surface document.cookie-set cookies across every Puppeteer browser
+        // backend (notably Firefox/WebDriver-BiDi), so sweep here too.
+        for (const entry of document.cookie.split(';')) {
+          const eq = entry.indexOf('=')
+          const name = (eq > -1 ? entry.slice(0, eq) : entry).trim()
+          if (name) document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`
+        }
+      })
+    )
+  }
+
+  // Catches HttpOnly cookies (and any the JS sweep above could not reach).
+  await bestEffort(async () => {
+    const context = page.browserContext()
+    const cookies = await context.cookies()
+    if (cookies.length) await context.deleteCookie(...cookies)
+  })
+
+  await bestEffort(() => page.goto('about:blank'))
+}

package/src/index.ts

@@ -28,6 +28,7 @@ export {
 } from './feature/helpers/launchDevServer.js'
 export { default as launchPage } from './feature/helpers/launchPage.js'
 export { default as providePuppeteerViteMatchers } from './feature/helpers/providePuppeteerViteMatchers.js'
+export { default as resetBrowserState } from './feature/helpers/resetBrowserState.js'
 export { default as visit } from './feature/helpers/visit.js'
 
 declare global {