test(browser): Cover the no-store + cookie-change bfcache miss

A no-store (CCNS) page is only evicted from bfcache once a cookie changes;
neither the header nor a cookie change blocks on its own. Add a `?botch=nostore`
case that serves the document with `Cache-Control: no-store` (via a preview
middleware, since a static server can't set per-request headers) and mutates a
cookie, asserting the `response-cache-control-no-store` reason.

Also trim the version-specific blocker details from the README so they don't
drift; the botch cases and their assertions are the source of truth.

Author: logaretm

CHANGELOG.md

@@ -16,7 +16,6 @@
   ```
 
   It emits:
-
   - `browser.bfcache.navigation` — a counter split by outcome (`hit`/`miss`) and navigation type.
   - `browser.bfcache.not_restored` — a counter of the (Chromium-only) `notRestoredReasons` for a miss.
   - `browser.bfcache.reload.duration` — a distribution of how expensive the fallback reload was on a miss.

dev-packages/e2e-tests/test-applications/browser-bfcache/README.md

@@ -17,17 +17,12 @@ Why this needs its own app rather than living in `browser-integration-tests`:
 - **Renderer-initiated navigation.** Restores are triggered with `history.back()` from the page;
   Playwright's CDP `goBack` bypasses bfcache.
 
-Blocker cases are version-sensitive (the pinned Chromium comes from the Playwright version) and real
-Chrome is more permissive than web.dev's blocker list suggests. Verified against the pinned Chrome:
+Which conditions actually block bfcache (and the exact reason strings) is version-specific and more
+permissive than web.dev's list suggests, so the individual `?botch=` cases and their assertions are
+the source of truth, not prose here. Some are gated on the browser version where behavior changed.
 
-- `unload` listener: blocks (stable across versions). Reason `unload-listener` (plus a `masked` one).
-- Open WebSocket: blocks only before Chrome 149, so that assertion is gated on the browser version.
-- IndexedDB: a plain open connection and even an in-flight transaction do NOT block; only a
-  connection holding up a version upgrade does (reason `idbversionchangeevent`).
-- `Cache-Control: no-store` and `beforeunload` no longer block.
-
-Reason extraction/classification (top/child/masked frames, nesting, caps) is exhaustively covered by
-the unit test at `packages/browser/test/integrations/bfcache.test.ts`; this app verifies the real
-end-to-end hit/miss + reason path for the deterministic blockers above.
+Reason extraction/classification (top/child/masked frames, nesting, caps) is covered by the unit test
+at `packages/browser/test/integrations/bfcache.test.ts`; this app verifies the real end-to-end
+hit/miss + reason path.
 
 If other tests later fit these same constraints, this app can be renamed to something broader.

dev-packages/e2e-tests/test-applications/browser-bfcache/src/main.ts

@@ -42,6 +42,13 @@ if (botch === 'websocket') {
   w.__ws = ws;
 }
 
+if (botch === 'nostore') {
+  // The document is served with `Cache-Control: no-store` (see vite.config.ts). A CCNS page is
+  // cached but evicted once a cookie changes, so mutate a cookie to force the miss.
+  document.cookie = 'bf=1; Path=/';
+  (window as unknown as { __nostoreReady?: boolean }).__nostoreReady = true;
+}
+
 if (botch === 'indexeddb') {
   // A plain open IndexedDB connection (or even an in-flight transaction) does NOT block bfcache in
   // current Chrome. What still blocks is a connection holding up a version upgrade: open v1 without

dev-packages/e2e-tests/test-applications/browser-bfcache/tests/bfcache.test.ts

@@ -45,7 +45,8 @@ test('reports a miss with notRestoredReasons when an unload listener blocks bfca
   const missPromise = waitForMetric(PROXY_SERVER_NAME, metric => isNavigation(metric, 'miss'));
   const unloadReasonPromise = waitForMetric(
     PROXY_SERVER_NAME,
-    metric => metric.name === 'browser.bfcache.not_restored' && attr(metric, 'browser.bfcache.reason') === 'unload-listener',
+    metric =>
+      metric.name === 'browser.bfcache.not_restored' && attr(metric, 'browser.bfcache.reason') === 'unload-listener',
   );
   // Chrome reports a privacy-masked reason alongside the real one; the integration must classify it
   // as a `masked` frame. This is our only real-browser coverage of the masked-frame path.
@@ -68,7 +69,8 @@ test('reports a miss with notRestoredReasons when an unload listener blocks bfca
   // The unload listener makes the page ineligible, so this back navigation is a fresh reload (a miss).
   await page.evaluate(() => history.back());
   await page.waitForFunction(
-    () => (performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined)?.type ===
+    () =>
+      (performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined)?.type ===
       'back_forward',
     { timeout: 5000 },
   );
@@ -157,6 +159,36 @@ test('reports a miss with an idbversionchangeevent reason when a connection bloc
   expect(attr(reason, 'browser.bfcache.frame')).toBe('top');
 });
 
+test('reports a miss with a response-cache-control-no-store reason when a CCNS page cookie changes', async ({
+  page,
+}) => {
+  const missPromise = waitForMetric(PROXY_SERVER_NAME, metric => isNavigation(metric, 'miss'));
+  const reasonPromise = waitForMetric(
+    PROXY_SERVER_NAME,
+    metric =>
+      metric.name === 'browser.bfcache.not_restored' &&
+      attr(metric, 'browser.bfcache.reason') === 'response-cache-control-no-store',
+  );
+
+  await page.goto('/?botch=nostore');
+  await page.waitForFunction(() => (window as unknown as { __nostoreReady?: boolean }).__nostoreReady === true, {
+    timeout: 5000,
+  });
+
+  await page.click('#to-page-2');
+  await page.waitForFunction(() => document.title === 'BFCache E2E - Page 2');
+  await page.waitForTimeout(500);
+
+  await page.evaluate(() => history.back());
+
+  const miss = await missPromise;
+  expect(miss.value).toBe(1);
+  expect(attr(miss, 'browser.bfcache.navigation_type')).toBe('back-forward');
+
+  const reason = await reasonPromise;
+  expect(attr(reason, 'browser.bfcache.frame')).toBe('top');
+});
+
 test('does not treat an ordinary forward navigation as a restore', async ({ page }) => {
   await page.goto('/');
   await page.waitForFunction(() => document.title === 'BFCache E2E - Page 1');

dev-packages/e2e-tests/test-applications/browser-bfcache/vite.config.ts

@@ -17,4 +17,31 @@ export default defineConfig({
   define: {
     'process.env.E2E_TEST_DSN': JSON.stringify(process.env.E2E_TEST_DSN),
   },
+  plugins: [
+    {
+      // The `?botch=nostore` case needs the document served with `Cache-Control: no-store`; a later
+      // cookie mutation then makes the browser evict the CCNS page from bfcache. Neither the header
+      // nor the cookie change blocks on its own - only the combination does. A static server can't
+      // set per-request headers, so add it here for that URL only.
+      name: 'bfcache-nostore-headers',
+      configurePreviewServer(server) {
+        server.middlewares.use((req, res, next) => {
+          if (req.url?.includes('botch=nostore')) {
+            res.setHeader('Cache-Control', 'no-store');
+            // vite's static handler runs after this and would otherwise reset Cache-Control to
+            // `no-cache`, so lock the header for this request only.
+            const originalSetHeader = res.setHeader.bind(res);
+            res.setHeader = (name, value) => {
+              if (String(name).toLowerCase() === 'cache-control') {
+                return res;
+              }
+
+              return originalSetHeader(name, value);
+            };
+          }
+          next();
+        });
+      },
+    },
+  ],
 });