Probes: prove what causes a mismatch

Use probes to prove the cause of a hydration mismatch. With --probe, hydration-proof reloads the affected page while changing one browser setting at a time. If the finding changes with that setting, the report names it as the cause.

Turn probes on

npx hydration-proof test --probe

You can also enable probes in the config with probes: true, or choose factors:

hydration-proof.config.ts

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  probes: { factors: ["time", "random"], maxPages: 5 },
});

Probes are off by default because each factor needs another page load.

How to prove the cause of a hydration mismatch

A regular finding suggests a likely cause based on its values and context. A probe tests that suggestion:

The page is loaded with the browser clock and Math.random() fixed.
It is loaded again, identically. This is the control.
It is loaded once more for each factor, with only that factor changed.
hydration-proof compares the finding across the loads.

Factor	What changes	Proves
`time`	The browser clock moves by 3 days, 7 hours, 11 minutes and 13 seconds	Time-dependent value
`random`	A different seed for `Math.random()` and `crypto.getRandomValues()`	Random value
`locale`	The browser locale becomes the server's (or another one)	Locale-dependent formatting
`timezone`	The browser timezone becomes the server's (or another one)	Timezone difference
`theme`	Light ↔ dark	Theme preference
`viewport`	Desktop ↔ mobile	Screen size or media query
`storage`	No `localStorage`, `sessionStorage` or `storageState` from the scenario (only when it has them)	Browser storage

The time probe moves the clock by an unusual amount so changes to a date or time are easier to spot.

Proven or likely?

When changing one factor changes or removes a finding, the terminal marks that cause as proven:

    HP1001 Text differs between server and client  (timezone difference, proven)
      #last-login  in LastLogin
      server: "Signed in at 5:00 AM"
      client: "Signed in at 10:00 AM"
 
  Probes
    HP1001 /dashboard #last-login  proven: timezone difference

The report also shows what changed and puts the proven cause's fixes first.

If several factors affect the finding, the report lists them. It also notes which factors made no difference.

What if an identical reload renders differently?

Look for changing server or API data. When identical loads disagree, the other probes cannot isolate a cause reliably. See server and client data.

What do probes cost?

Probes run only for value mismatches: text, attributes, styles, classes, dangerouslySetInnerHTML, and form state (HP1001 to HP1006, HP1012 and HP1013). Ignored, suppressed and info findings are skipped.

Each probed page costs up to 9 extra page loads: the fixed load, the control, and one per factor.
maxPages (default 5) caps the pages probed per run. Pages with the most errors go first, and a note says how many were left out.
The run ends with a note of how many extra loads the probes took.

If you already suspect a cause, narrow factors to save page loads.

Probes never hide a finding

Probes change the test browser, not the server. A fixed browser clock makes loads comparable; it does not stop the check from finding a server/client difference. The clock and randomSeed scenario options work the same way.

Options

Option	Type	Default	Description
factors	ProbeFactor[]	all that apply	What to vary.
maxPages	number	5	Most pages probed per run.

How hydration-proof works: stages, comparisons and causes
All causes of hydration errors and their fixes
Environment matrix: find the locale or browser a bug needs
Fix date and time hydration errors
HP1001: text differs between server and client

Prove the cause of a hydration mismatch