@rvoh/psychic-spec-helpers 3.0.1 → 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.1",
+  "version": "3.1.0",
   "description": "psychic framework spec helpers",
   "author": "RVO Health",
   "repository": {
@@ -29,8 +29,8 @@
     "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"
@@ -60,7 +60,7 @@
     "globals": "^16.5.0",
     "koa-bodyparser": "^4.4.1",
     "koa-conditional-get": "^3.0.0",
-    "kysely": "^0.28.13",
+    "kysely": "^0.28.14",
     "kysely-codegen": "~0.19.0",
     "luxon-jest-matchers": "^0.1.14",
     "openapi-typescript": "^7.10.1",

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 {