Hydration mismatch during rapid state updates in newSpec

Question

When testing Stencil components using the @stencil/core testing library, maintaining consistency between the initial server-rendered state and the client-side DOM is critical. While the newSpec utility facilitates mounting components and simulating lifecycle methods, certain state-driven updates can trigger hydration mismatch warnings.
The issue arises specifically when rapid-fire state re-renders occur immediately after the component mounts. This creates a potential race condition where the test assertion may execute before the virtual DOM has fully synchronized with the asynchronous state, leading to inconsistent test results that do not reflect production-like behavior.

How does the Stencil runtime handle the priority of asynchronous CSS transitions during these rapid render cycles?
Is there a configuration option to ensure the hydration process completes fully before newSpec assertions are evaluated?

Tasadduq Burney · Answer

Direct answer
CSS transitions do not change hydration priority in Stencil, and there is no configuration option in @stencil/core testing that forces hydration to be fully complete before newSpec assertions run.
Confirmed: Stencil’s runtime processes CSS transitions through the normal Web Animations API / requestAnimationFrame path. Transitions run at normal animation priority and do not block or delay hydration work. There is no internal priority inversion that makes transitions finish before hydration.
Confirmed: The testing API newSpec mounts components in a JSDOM environment. The mount promise resolves once the initial render is scheduled, but attribute reconciliation, event binding and style application continue asynchronously on the microtask queue. No flag such as waitForHydration exists in @stencil/core/testing to make assertions wait for that work.
Likely explanation for the warning you see
The hydration mismatch warning in newSpec is most likely a test-timing race, not a production hydration bug. Rapid @State/@Prop changes fired in componentDidLoad or synchronously in the test body schedule extra render cycles that interleave with the pending hydration microtasks. The assertion executes before the virtual DOM has caught up with the server-rendered markup, so JSDOM reports a difference. In a real browser with a paint cycle the same pattern rarely surfaces because user interaction occurs after hydration completes.
Steps needed for this case

Await the mount and then flush Stencil’s async queue before asserting.
const page = await newSpec(Page);
await page.waitForChanges();
// assert
After any rapid state mutation, flush again.
component.count = 1;
await page.waitForChanges();
await page.flushQueue();
If the component relies on paint timing, let one animation frame pass.
await new Promise(r => requestAnimationFrame(r));
Keep the test deterministic: avoid firing multiple synchronous state updates in componentDidLoad. Batch them or move them to componentWillLoad where possible.

Do not use setTimeout(...,0) or bare Promise.resolve().then() as a wait; they are flaky. Prefer waitForChanges and flushQueue which wrap the Stencil scheduler and rAF.
One diagnostic detail that changes the recommendation: are you mounting against prerendered SSR markup in the test, or mounting a client-only component? If SSR markup is present, the flush pattern above is required. If the test is client-only, the mismatch warning can usually be suppressed by asserting after the first waitForChanges and not treating the warning as a failure.

Hydration mismatch during rapid state updates in newSpec

1 answer

Direct answer

Likely explanation for the warning you see

Steps needed for this case

Your perspective belongs here.

0 question comments