GitHub v1.3.1

Testing Plugin

Plugin

Documentation for the Coralite testing plugin and its automatic data-testid generation.

The testingPlugin is a built-in Coralite utility activated when the mode: 'testing' configuration option is set. It is designed to assist in End-to-End (E2E) testing by providing deterministic selectors for DOM elements and disabling animations.

Automatic data-testid Generation

In testing mode, the testing plugin automatically duplicates all ref="xyz" attributes into data-testid attributes. Because Coralite isolates references across component instances, these data-testid attributes are resolved into a strict namespace pattern.

Additionally, the testing plugin auto-injects data-testid attributes onto interactive elements (such as button, a, input, select, textarea, elements with tabindex, or elements with interactive ARIA roles) and custom elements, using the pattern [instanceId]__[tagName]-[index].

Namespace Pattern

The generated data-testid follows this format:

text
Code copied!
[componentId]__[refName]-[instanceIndex]

Example:

html
Code copied!
  <!-- Source Component Template (my-button.html) -->
  <template id="my-button">
    <button ref="btn">Click me</button>
  </template>
  
  <!-- Rendered Output (Testing Mode) -->
  <button ref="my-button__btn-0">Click me</button>

E2E Testing Usage

When using a testing framework like Playwright, you can use these deterministic IDs to select elements even if they are deeply nested or part of multiple component instances.

JavaScript
Code copied!
  // Playwright example
  test('should click the button', async ({ page }) => {
    await page.goto('/');
    // Await hydration
    await page.evaluate(() => window.__coralite__.lifecycle.hydrated);
  
    // Select using the namespaced test ID
    await page.getByTestId('my-button__btn-0').click();
  });

Key Points

  • Testing-Only: The plugin only runs when mode is 'testing'. It does not run in development or production modes, ensuring your production builds remain clean.
  • Automatic: No manual configuration is required; it hooks into onBeforeComponentRender and onPageSet.
  • Deterministic: Provides a reliable way to target specific component instances in complex layouts.