Scenarios and sign-in

To test signed-in pages for hydration errors, add a scenario for each kind of user. A scenario sets the browser's locale, timezone, viewport and sign-in state. Its login runs once; the resulting cookies and storage are reused for the pages in that scenario.

What a scenario is

Without scenarios, the tool uses one scenario named default. It uses your machine's locale and timezone and a light color scheme. Add more scenarios when your users see the app under different conditions.

List scenarios to test the environments your users have:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "dark-mobile", colorScheme: "dark", viewport: "mobile" },
    { name: "karachi", locale: "ur-PK", timezoneId: "Asia/Karachi" },
  ],
});

The report names the scenario for each page. To test just one, pass its name:

npx hydration-proof test --scenario dark-mobile

Locale, timezone, theme and viewport

To cover several combinations without listing each scenario by hand, use the environment matrix.

Test signed-in pages for hydration errors

Hydration problems can hide behind a login—for example, a dashboard date or an admin table that reads localStorage. Choose one way to sign in:

1. cookies: pass a session cookie when your test environment can issue one. No browser login is needed.
2. storageState: reuse a Playwright session saved with context.storageState({ path }).
3. login: sign in through the app. This runs once per scenario, not once for every page.

An authorization entry in headers works too.

This example separates public, customer and admin pages. Replace the order ID and selectors with values from your app:

import { defineConfig } from "hydration-proof";
 
function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running hydration-proof`);
  return value;
}
 
export default defineConfig({
  routes: {
    dynamic: { "/account/orders/[id]": ["your-stable-test-order-id"] },
  },
 
  scenarios: [
    // Everything that is not behind a login
    { name: "guest", exclude: ["/account/**", "/admin/**"] },
 
    // A real sign-in, once, then reused for every page of this scenario
    {
      name: "customer",
      include: ["/account/**"],
      login: async ({ page, baseUrl }) => {
        await page.goto(`${baseUrl}/login`);
        await page.fill("#email", requiredEnv("TEST_USER_EMAIL"));
        await page.fill("#password", requiredEnv("TEST_USER_PASSWORD"));
        await page.click("button[type=submit]");
        await page.waitForURL("**/account");
      },
    },
 
    // A session the test environment hands out: no browser work at all
    {
      name: "admin",
      include: ["/admin/**"],
      cookies: [{ name: "session", value: requiredEnv("ADMIN_SESSION") }],
    },
  ],
});

Set the credentials in the environment before running the test:

TEST_USER_EMAIL=… TEST_USER_PASSWORD=… ADMIN_SESSION=… npx hydration-proof test

How the login runs

• login receives { page, baseUrl }: a Playwright page in a browser context with the scenario's settings, and the URL of the tested app.
• It runs once per run, after the app is up and after hooks.setup.
• A login that throws stops the run with exit code 2 and the error message.
• Cookies without a domain apply to the tested app.
• Keep credentials in environment variables, not in the config file, which gets committed.

When a signed-in page ends on the login page

If a signed-in route ends on the login page, it gets an HP9010 warning. Check that login waits for the redirect, the cookie belongs to this domain and the session has not expired. Run with --headed --workers 1 to watch the sign-in. If the route should redirect, set expectRedirect instead; see routes.

Split public, customer and admin pages

Use include and exclude to choose each scenario's routes. * matches one path segment and ** matches any number. A route no scenario includes is not tested; keep a guest scenario for public pages.

Mock browser requests

mocks return fixed responses to browser requests. Use them when live data would make a page change between test runs:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  scenarios: [
    {
      name: "default",
      mocks: [{ url: "**/api/metrics", body: { signups: 12, revenue: 3400 } }],
    },
  ],
});

url accepts a glob or a RegExp. Object bodies are sent as JSON. Mocks affect browser requests only; they do not replace data fetched by the server while rendering. They also disable the browser's HTTP cache.

Seed data before the pages load

To create users or seed a database, use hooks.setup in the config. It runs once per build mode, after the app is up and before the scenario logins, and may return a teardown function. Sign-in itself belongs in a scenario's login: there is no global setup hook.

Fixed clock and random values

clock fixes the browser time for Date.now() and new Date(), and randomSeed seeds Math.random() and crypto.getRandomValues() in the browser. Both are diagnostic: they make the client values repeatable between runs, but the server keeps its real clock, so time-dependent and random output is still found. To prove that the clock or randomness causes a finding, use probes.

More scenario options

• headers: extra request headers
• localStorage and sessionStorage: entries written before any page script runs
• initScripts: code run before page scripts
• query: query parameters added to every URL, such as { currency: "EUR" }
• browser: "chromium", "firefox" or "webkit" for this scenario
• network: "fast-3g", "slow-3g" or a custom profile
• cpu: slow JavaScript down by a factor (Chromium only)
• cache: "warm" loads each page once before testing it, like a returning visitor (the default is "cold")

All scenario options

Related

• Test locales and timezones with the environment matrix
• Prove what causes a mismatch
• Choose which routes are tested
• Keep secrets out of reports
• Configuration reference