@next/playwright 16.2.0-canary.100

package/README.md

@@ -0,0 +1,107 @@
+# @next/playwright
+
+> - **Status:** Experimental. This API is not yet stable.
+> - **Requires:** [Cache Components](https://nextjs.org/docs) to be enabled.
+
+Playwright helpers for testing Next.js applications.
+
+## Instant Navigation Testing
+
+An **instant navigation** commits immediately without waiting for data fetching.
+The cached shell — including any Suspense loading boundaries — renders right
+away, and dynamic data streams in afterward. The shell is the instant part, not
+the full page.
+
+`instant()` lets you test whether a route achieves this. While the callback is
+active, navigations render only cached and prefetched content. Dynamic data is
+deferred until the callback returns. This lets you make deterministic assertions
+against the shell without race conditions.
+
+The tool assumes a warm cache: all prefetches have completed and all cacheable
+data is available. This way you're testing whether the route is *structured
+correctly* for instant navigation, independent of network timing. If content you
+expected to be cached is missing inside the callback, it points to a problem — a
+missing `use cache` directive, a misplaced Suspense boundary, or a similar gap.
+
+### Examples
+
+**Loading shell appears instantly** (dynamic content behind a Suspense boundary):
+
+```ts
+import { instant } from '@next/playwright'
+
+test('shows loading shell during navigation', async ({ page }) => {
+  await page.goto('/')
+
+  await instant(page, async () => {
+    await page.click('a[href="/dashboard"]')
+
+    // The loading shell is visible — dynamic data is deferred
+    await expect(page.locator('[data-testid="loading"]')).toBeVisible()
+  })
+
+  // After instant() returns, dynamic data streams in normally
+  await expect(page.locator('[data-testid="content"]')).toBeVisible()
+})
+```
+
+**Fully instant navigation** (all content is cached):
+
+```ts
+test('navigates to profile instantly', async ({ page }) => {
+  await page.goto('/')
+
+  await instant(page, async () => {
+    await page.click('a[href="/profile"]')
+
+    // All content renders immediately
+    await expect(page.locator('[data-testid="profile-name"]')).toBeVisible()
+    await expect(page.locator('[data-testid="profile-bio"]')).toBeVisible()
+  })
+})
+```
+
+### Enabling in production builds
+
+In development (`next dev`), the testing API is available by default. In
+production builds, it is disabled unless you explicitly opt in:
+
+```js
+// next.config.js
+module.exports = {
+  experimental: {
+    exposeTestingApiInProductionBuild: true,
+  },
+}
+```
+
+This is not meant to be deployed to live production sites. Only enable it in
+controlled testing environments like preview deployments or CI.
+
+## How it works
+
+`instant()` sets a cookie that tells Next.js to serve only cached data during
+navigations. While the cookie is active:
+
+- **Client-side navigations**: The router renders only what is available in the
+  prefetch cache. Dynamic data is deferred until the cookie is cleared.
+- **Server renders (initial load, reload, MPA navigation)**: The server responds
+  with only the static shell, without any per-request dynamic data.
+
+When the callback completes, the cookie is cleared and normal behavior resumes.
+
+## Design
+
+The layering between this package and Next.js is intentionally very thin. This
+serves as a reference implementation that other testing frameworks and dev tools
+can replicate with minimal effort. The entire mechanism is a single cookie:
+
+```ts
+// Set the cookie to enter instant mode
+document.cookie = 'next-instant-navigation-testing=1; path=/'
+
+// ... run assertions ...
+
+// Clear the cookie to resume normal behavior
+document.cookie = 'next-instant-navigation-testing=; path=/; max-age=0'
+```

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal interfaces for Playwright's Page and BrowserContext. We use
+ * structural types rather than importing from a specific Playwright package
+ * so this works with any version of playwright, playwright-core, or
+ * @playwright/test.
+ */
+interface PlaywrightBrowserContext {
+    addCookies(cookies: Array<{
+        name: string;
+        value: string;
+        url?: string;
+        domain?: string;
+        path?: string;
+    }>): Promise<void>;
+    cookies(): Promise<Array<{
+        name: string;
+        value: string;
+    }>>;
+    clearCookies(options?: {
+        name?: string;
+        domain?: string;
+        path?: string;
+    }): Promise<void>;
+}
+interface PlaywrightPage {
+    url(): string;
+    context(): PlaywrightBrowserContext;
+}
+/**
+ * Runs a function with instant navigation enabled. Within this scope,
+ * navigations render the prefetched UI immediately and wait for the
+ * callback to complete before streaming in dynamic data.
+ *
+ * Uses the cookie-based protocol: setting the cookie acquires the
+ * navigation lock (via CookieStore change event), and clearing it
+ * releases the lock.
+ *
+ * If the page is already loaded, the URL is inferred
+ * automatically. For a fresh page (before any navigation), pass
+ * `baseURL` so the cookie can be scoped to the correct domain:
+ *
+ *   await instant(page, async () => {
+ *     await page.goto(url)
+ *     // ...
+ *   }, { baseURL: 'http://localhost:3000' })
+ *
+ * When `@playwright/test` is installed, acquire/release actions appear
+ * as labeled steps in the Playwright UI.
+ */
+export declare function instant<T>(page: PlaywrightPage, fn: () => Promise<T>, options?: {
+    baseURL?: string;
+}): Promise<T>;
+export {};

package/dist/index.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instant = instant;
+const step_1 = require("./step");
+const INSTANT_COOKIE = 'next-instant-navigation-testing';
+/**
+ * Runs a function with instant navigation enabled. Within this scope,
+ * navigations render the prefetched UI immediately and wait for the
+ * callback to complete before streaming in dynamic data.
+ *
+ * Uses the cookie-based protocol: setting the cookie acquires the
+ * navigation lock (via CookieStore change event), and clearing it
+ * releases the lock.
+ *
+ * If the page is already loaded, the URL is inferred
+ * automatically. For a fresh page (before any navigation), pass
+ * `baseURL` so the cookie can be scoped to the correct domain:
+ *
+ *   await instant(page, async () => {
+ *     await page.goto(url)
+ *     // ...
+ *   }, { baseURL: 'http://localhost:3000' })
+ *
+ * When `@playwright/test` is installed, acquire/release actions appear
+ * as labeled steps in the Playwright UI.
+ */
+async function instant(page, fn, options) {
+    // Check for nested instant() calls. The cookie is scoped to the browser
+    // context, so we can detect nesting by checking if it's already set.
+    const existingCookies = await page.context().cookies();
+    if (existingCookies.some((c) => c.name === INSTANT_COOKIE)) {
+        throw new Error('An instant() scope is already active. Nesting instant() ' +
+            'calls is not supported. Did you forget to await the ' +
+            'previous instant() call?');
+    }
+    // Acquire the lock by setting the cookie via the browser context. This
+    // ensures the cookie is present even on the very first navigation.
+    // The cookie triggers the CookieStore change event in
+    // navigation-testing-lock.ts, which acquires the in-memory navigation lock.
+    const { hostname } = new URL(resolveURL(page, options));
+    await (0, step_1.step)('Acquire Instant Lock', () => page
+        .context()
+        .addCookies([
+        { name: INSTANT_COOKIE, value: '[0]', domain: hostname, path: '/' },
+    ]));
+    try {
+        return await fn();
+    }
+    finally {
+        // Release the lock by clearing the cookie. Next.js may have updated the
+        // cookie value (e.g. from [0] to [1,null]) during the lock scope. We
+        // clear by name to remove the cookie regardless of its current value or
+        // which domain variant it was stored under.
+        await (0, step_1.step)('Release Instant Lock', () => page.context().clearCookies({ name: INSTANT_COOKIE }));
+    }
+}
+/**
+ * Resolves the URL to scope the instant navigation cookie to. Prefers
+ * an explicit `baseURL` option, then falls back to the page's current URL.
+ * Throws a descriptive error if neither is available (e.g. fresh page
+ * before any navigation).
+ */
+function resolveURL(page, options) {
+    var _a;
+    const url = (_a = options === null || options === void 0 ? void 0 : options.baseURL) !== null && _a !== void 0 ? _a : page.url();
+    if (url && url !== 'about:blank') {
+        return url;
+    }
+    const error = new Error(`Could not infer the base URL of the application.
+
+instant() needs to know the base URL so it can configure the
+browser before the first page load. If the page is already
+loaded, the base URL is detected automatically.
+Otherwise, you can fix this in one of two ways:
+
+1. Pass a baseURL option:
+
+  await instant(page, async () => {
+    await page.goto('http://localhost:3000')
+    // ...
+  }, { baseURL: 'http://localhost:3000' })
+
+  Tip: If you use baseURL in your Playwright config, you can
+  get it from the test fixture:
+
+    test('my test', async ({ page, baseURL }) => {
+      await instant(page, async () => {
+        // ...
+      }, { baseURL })
+    })
+
+2. Navigate to a page before calling instant():
+
+  await page.goto('http://localhost:3000')
+  await instant(page, async () => {
+    // ...
+  })`);
+    // Remove resolveURL and instant from the stack trace so the error
+    // points at the caller's code.
+    Error.captureStackTrace(error, instant);
+    throw error;
+}

package/dist/step.d.ts

@@ -0,0 +1,8 @@
+export type Step = <T>(title: string, body: () => Promise<T>) => Promise<T>;
+/**
+ * When `@playwright/test` is installed and we're running inside the Playwright
+ * test runner, wraps the body in a `test.step()` so it appears as a labeled
+ * step in the Playwright UI. Otherwise just executes the body directly.
+ */
+declare let step: Step;
+export { step };

package/dist/step.js

@@ -0,0 +1,33 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.step = void 0;
+/**
+ * When `@playwright/test` is installed and we're running inside the Playwright
+ * test runner, wraps the body in a `test.step()` so it appears as a labeled
+ * step in the Playwright UI. Otherwise just executes the body directly.
+ */
+let step = (_title, body) => body();
+exports.step = step;
+try {
+    const pw = require('@playwright/test');
+    if (typeof ((_a = pw.test) === null || _a === void 0 ? void 0 : _a.step) === 'function') {
+        const playwrightStep = pw.test.step;
+        exports.step = step = async (title, body) => {
+            try {
+                return await playwrightStep(title, body);
+            }
+            catch (e) {
+                // If test.step fails because we're not inside the Playwright test
+                // runner (e.g., running under Jest), fall back to executing the body
+                // directly without step labels.
+                if (e instanceof Error &&
+                    e.message.includes('can only be called from a test')) {
+                    return body();
+                }
+                throw e;
+            }
+        };
+    }
+}
+catch { }

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@next/playwright",
+  "version": "16.2.0-canary.100",
+  "repository": {
+    "url": "vercel/next.js",
+    "directory": "packages/next-playwright"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "node ../../scripts/rm.mjs dist && tsc -d -p tsconfig.json",
+    "prepublishOnly": "cd ../../ && turbo run build",
+    "dev": "tsc -d -w -p tsconfig.json",
+    "typescript": "tsec --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "5.9.2"
+  }
+}