Hydration Readiness & E2E Testing
This reference details the technical specifications of Coralite's client-side hydration phase and how it exposes its state for End-to-End (E2E) testing frameworks.
Testing Plugin (data-testid) #
When Coralite is configured with mode: 'development', it automatically activates a built-in testing plugin.
During the AST build phase, this plugin recursively traverses all component templates (both declarative and imperative). Because Coralite isolates references across component instances, the underlying ref strings have already been resolved by the core framework into a strict namespace pattern: [componentId]__[refName]-[index]. Whenever the testing plugin encounters one of these resolved ref attributes, it duplicates that exact namespaced value into a data-testid attribute.
This ensures that E2E testing frameworks can target highly specific element instances deterministically using the standard data-testid selector pattern without requiring developers to manually maintain duplicate attributes, and guaranteeing these testing hooks are entirely stripped from production builds.
The window.__coralite_ready__ Promise #
Coralite injects a global promise named window.__coralite_ready__ into the built HTML document. This promise acts as a reliable hook to signal the absolute completion of the client-side hydration phase.
Resolution Lifecycle Pipelines #
The framework strict-awaits the hydration process, ensuring the window.__coralite_ready__ promise only resolves after two critical asynchronous pipelines finish:
| Pipeline | Internal Variable | Description |
|---|---|---|
| Component Definition | loadPromises |
The framework scans the DOM, dynamically imports the required module chunks for any custom elements found on the current page, and registers them via the browser's native customElements.define() API. |
| Declarative Scripts | declarativePromises |
The framework fully executes the asynchronous client.script blocks (defined in defineComponent) for all declarative component instances mapped on the page. |
E2E Testing Implications #
Because end-to-end testing frameworks (like Playwright or Cypress) interact with the DOM much faster than front-end hydration completes, tests MUST wait for this promise immediately after page navigation.
Failing to wait for this promise can lead to race conditions where the test runner attempts to click buttons, select inputs, or assert component state before the custom elements have actually mounted or initialized their internal variables, leading to flaky or failing tests.
For practical examples on how to implement this in popular testing frameworks, see the E2E Testing Guide.