Playwright Tests for Alpine.js Components in the Hyvä Theme

1. Why CSS selectors alone are not enough for Alpine components

In classic server-rendered Magento templates, a Playwright selector like page.locator('.minicart-wrapper') is usually enough, because a component's state is directly visible in the delivered HTML. In a Hyvä theme, a significant part of that state instead lives in the reactive Alpine state behind x-data, not in the DOM. A dropdown can look open while the underlying boolean is still false during a transition, and a test that only checks visibility never catches that difference.

Testing only against CSS classes or text content really means testing the rendering result of an interaction, not the interaction itself. For experienced Hyvä developers it pays off to treat Alpine state as its own verifiable source of truth and write tests that validate both the visible DOM state and the underlying reactive state against each other, because only together do they prove that a component actually works correctly.

2. Reading Alpine state directly through the public Alpine API

Since version 3, Alpine.js ships an official, public method, Alpine.$data(el), for reading an element's reactive data context from the outside. Because Playwright executes directly inside the browser context through the Chrome DevTools Protocol, this method can be called inside page.evaluate() exactly as it would be in the browser console, without any detour through visible DOM attributes.

For a Hyvä mini-cart or a filter panel, that means a test can read a property like open or selectedCount directly, instead of inferring it indirectly from CSS classes like is-open, which can be named differently depending on the template version. That makes assertions far more resilient against purely cosmetic refactors that never touch the underlying state at all.

// utils/alpine-state.ts
import type { Page } from '@playwright/test';

export async function getAlpineData<T = Record<string, unknown>>(
  page: Page,
  selector: string,
): Promise<T> {
  return page.evaluate((sel) => {
    const el = document.querySelector(sel);
    if (!el) throw new Error(`Element not found: ${sel}`);
    // @ts-expect-error Alpine is exposed globally by Hyva
    return window.Alpine.$data(el);
  }, selector);
}

test('mini cart opens after clicking the toggle', async ({ page }) => {
  await page.locator('[data-testid="minicart-toggle"]').click();
  const state = await getAlpineData(page, '[x-data="initMiniCart"]');
  expect(state.open).toBe(true);
});

3. Waiting for Alpine initialization instead of fixed timeouts

A page.waitForTimeout(500) before the first interaction is one of the most common causes of flaky tests in Alpine-heavy themes, because the actual initialization time depends on network latency, server load and the number of components registered on a given page. After processing every x-data root, Alpine fires an alpine:initialized event on the document, which serves as a precise, deterministic anchor point instead.

So that this event is never missed because it may already have fired before the first page.evaluate() call, the listener is registered through page.addInitScript(), before any navigation happens at all. The test then simply waits on a promise that resolves exactly when Alpine is actually finished, regardless of whether that happens after fifty or after eight hundred milliseconds.

test.beforeEach(async ({ page }) => {
  await page.addInitScript(() => {
    (window as any).__alpineReady = new Promise((resolve) => {
      document.addEventListener('alpine:initialized', () => resolve(true), { once: true });
    });
  });
});

test('filter panel is interactive after initialization', async ({ page }) => {
  await page.goto('/women/jackets.html');
  await page.evaluate(() => (window as any).__alpineReady);
  await page.locator('[data-testid="filter-toggle"]').click();
});

4. CSP-restrictive Hyvä setups and their effect on tests

A theme built on the CSP variant parent hyva-themes/magento2-default-theme-csp uses the @alpinejs/csp build, which, unlike the standard build, never evaluates arbitrary JavaScript strings inside x-data and instead only allows named components previously registered through Alpine.data(). That matters for tests, because a selector like x-data='{ open: false }' simply does not exist in such a setup, and a named component like x-data='initMiniCart' is used instead.

A common worry is that the restrictive content security policy also blocks a project's own Playwright scripts once they inject code into the page through page.evaluate(). In practice that is not the case, because Chromium executes code run through the DevTools protocol with elevated privileges outside the regular script pipeline, so the page's CSP simply does not apply to Runtime.evaluate calls. A test is free to introspect even though the page itself is tightly locked down.

5. Introducing a stable data-testid convention in Hyvä templates

Hyvä templates ship with no test attributes out of the box, which pushes tests toward either CSS classes meant for styling rather than test automation, or text content that differs between the German and the English store view. A dedicated, language-independent data-testid convention placed directly in the .phtml overrides solves both problems at once and stays stable even after a Tailwind refactor that only touches utility classes.

It matters to document the convention centrally, for example as a naming scheme built from module, component and action such as minicart-toggle or filter-panel-apply, so team members don't each invent their own pattern independently. Because data-testid attributes are plain HTML attributes with no script character at all, they have zero effect on the content security policy and can safely stay in production markup.

6. Practical example: testing the mini-cart dropdown by state

The mini-cart dropdown shows how testid and Alpine state combine into a solid assertion: the click on the toggle button goes through a stable data-testid selector, while the actual check, whether the dropdown opened and how many items are shown, runs directly against the Alpine properties open and itemCount. That makes the test independent of whether the dropdown fades in or out via a CSS transition.

This combination also makes the difference between a purely visual and a functional bug visible: if the transition breaks, Playwright still reports an open state, but the visibility check fails, so the test precisely points to which layer the problem actually lives in, instead of only reporting that something, somewhere, is wrong.

test('mini cart shows the correct item count after adding a product', async ({ page }) => {
  await page.goto('/backpack-classic.html');
  await page.locator('[data-testid="add-to-cart"]').click();
  await page.waitForResponse((res) => res.url().includes('/graphql') && res.status() === 200);

  const state = await getAlpineData(page, '[x-data="initMiniCart"]');
  expect(state.itemCount).toBe(1);
  await expect(page.locator('[data-testid="minicart-badge"]')).toHaveText('1');
});

7. Race conditions between GraphQL responses and Alpine re-rendering

Clicking Add to Cart in a Hyvä theme triggers a fetch call against the GraphQL API, whose response only updates the reactive Alpine property once it succeeds. Between the promise resolving and the actual DOM update sits Alpine's own effect scheduler, which batches changes through a microtask before patching the DOM. A test that asserts right after the click therefore often still sees the old state, even though the click technically succeeded.

Instead of bolting on a fixed delay, combine page.waitForResponse() for the GraphQL call with Playwright's auto-retrying assertions like expect(locator).toHaveText(), which internally keep re-checking until either the expected value shows up or a timeout is hit. This combination mirrors the actual sequence of network response and reactive re-render, instead of papering over it with a guessed pause.

8. Building a page object pattern for Alpine components

Once several tests repeat the same Alpine selector and the same $data query, a small wrapper following the classic page object pattern pays off, adapted to Alpine state instead of pure DOM structure. A class like MiniCart then bundles methods such as open(), isOpen() and itemCount(), so a test stays readable and internal details like the exact x-data name are known in exactly one place in the project.

If the registered Alpine component's name changes later, for example because a refactor renames initMiniCart to useMiniCart, only the page object needs updating, not every single test that touches the mini cart. This pattern significantly reduces the maintenance burden of a growing test suite and turns Alpine state access into a reusable building block instead of repeated boilerplate.

export class MiniCart {
  constructor(private readonly page: Page) {}

  async open() {
    await this.page.locator('[data-testid="minicart-toggle"]').click();
  }

  async isOpen(): Promise<boolean> {
    const state = await getAlpineData(this.page, '[x-data="initMiniCart"]');
    return Boolean(state.open);
  }

  async itemCount(): Promise<number> {
    const state = await getAlpineData<{ itemCount: number }>(
      this.page,
      '[x-data="initMiniCart"]',
    );
    return state.itemCount;
  }
}

9. Integrating Playwright tests reliably into the CI pipeline

In a CI pipeline, Playwright should run against a dedicated Hyvä instance seeded with test data, whose catalog, customer accounts and prices are deterministic, so assertions never depend on random production data. Retries at the test level, for example two retries per failed test, absorb remaining network jitter without hiding real regressions, as long as the retry rate is tracked separately in the report.

For debugging it pays off to record traces only on the first retry instead of on every run, keeping artifact size and runtime under control while still providing a complete timeline of network calls and DOM snapshots when something actually fails. That keeps the pipeline fast enough for daily use while still leaving enough context to narrow down a failure without local reproduction.

playwright:
  stage: test
  image: mcr.microsoft.com/playwright:v1.47.0-jammy
  script:
    - npm ci
    - npx playwright test --project=chromium --retries=2 --trace=on-first-retry
  artifacts:
    when: always
    paths:
      - playwright-report/
      - test-results/
    expire_in: 7 days

10. Summary

11. FAQ: Playwright and Alpine.js in the Hyvä Theme: Key Takeaways