Playwright-Tests für Alpine.js-Komponenten im Hyvä-Theme

1. Warum CSS-Selektoren allein bei Alpine-Komponenten nicht ausreichen

In klassischen serverseitig gerenderten Magento-Templates reicht ein Playwright-Selektor wie page.locator('.minicart-wrapper') meist aus, weil der Zustand einer Komponente unmittelbar im ausgelieferten HTML sichtbar ist. Im Hyvä-Theme lebt ein erheblicher Teil des Zustands dagegen nicht im DOM, sondern im reaktiven Alpine-State hinter x-data. Ein Dropdown kann geöffnet aussehen, obwohl das zugrunde liegende Boolean noch false ist, während ein Übergang läuft, und ein Test, der nur die Sichtbarkeit prüft, deckt diesen Unterschied nicht auf.

Wer ausschließlich gegen CSS-Klassen oder Textinhalte testet, prüft in Wahrheit das Rendering-Ergebnis einer Interaktion, nicht die Interaktion selbst. Für erfahrene Hyvä-Entwickler lohnt es sich deshalb, den Alpine-State als eigene, prüfbare Quelle der Wahrheit zu behandeln und Tests so zu schreiben, dass sie sowohl den sichtbaren DOM-Zustand als auch den zugrunde liegenden reaktiven Zustand gegeneinander validieren, denn erst beide zusammen beweisen, dass eine Komponente wirklich korrekt funktioniert.

2. Alpine-State direkt über die öffentliche Alpine-API auslesen

Alpine.js stellt seit Version 3 mit Alpine.$data(el) eine offizielle, öffentliche Methode bereit, um den reaktiven Datenkontext eines Elements von außen auszulesen. Da Playwright über das Chrome DevTools Protocol direkt im Browserkontext ausführt, lässt sich diese Methode innerhalb von page.evaluate() genauso aufrufen wie in der Browserkonsole, ohne dass ein Umweg über sichtbare DOM-Attribute nötig wäre.

Für einen Hyvä-Mini-Cart oder ein Filter-Panel bedeutet das, dass ein Test den Wert einer Eigenschaft wie open oder selectedCount unmittelbar abfragen kann, statt ihn indirekt aus CSS-Klassen wie is-open abzuleiten, die je nach Template-Version unterschiedlich benannt sein können. Das macht Assertions deutlich robuster gegen rein optische Refactorings, die den eigentlichen Zustand gar nicht verändern.

// 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 nicht gefunden: ${sel}`);
    // @ts-expect-error Alpine wird global von Hyva bereitgestellt
    return window.Alpine.$data(el);
  }, selector);
}

test('Mini-Cart oeffnet sich nach Klick auf den 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. Auf die Alpine-Initialisierung warten statt fester Timeouts

Ein page.waitForTimeout(500) vor der ersten Interaktion ist einer der häufigsten Gründe für Flaky Tests in Alpine-lastigen Themes, weil die tatsächliche Initialisierungsdauer von Netzwerklatenz, Serverauslastung und der Zahl der auf einer Seite registrierten Komponenten abhängt. Alpine feuert, nachdem alle x-data-Wurzeln verarbeitet wurden, ein alpine:initialized-Event auf dem Dokument, das sich als präziser, deterministischer Ankerpunkt eignet.

Damit dieses Event nicht verpasst wird, weil es unter Umständen bereits vor dem ersten page.evaluate-Aufruf gefeuert ist, registriert man den Listener über page.addInitScript(), also bevor überhaupt navigiert wird. Anschließend wartet der Test lediglich auf ein Promise, das genau dann aufgelöst wird, wenn Alpine tatsächlich fertig ist, unabhängig davon, ob das nach fünfzig oder nach achthundert Millisekunden der Fall ist.

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

test('Filterpanel ist nach der Initialisierung bedienbar', async ({ page }) => {
  await page.goto('/damen/jacken.html');
  await page.evaluate(() => (window as any).__alpineReady);
  await page.locator('[data-testid="filter-toggle"]').click();
});

4. CSP-restriktive Hyvä-Setups und ihre Auswirkung auf Tests

Ein Theme, das auf dem CSP-Varianten-Parent hyva-themes/magento2-default-theme-csp basiert, nutzt das @alpinejs/csp-Build, das anders als der Standard-Build keine beliebigen JavaScript-Strings in x-data auswertet, sondern ausschließlich zuvor über Alpine.data() registrierte, benannte Komponenten erlaubt. Für Tests ist das relevant, weil sich Selektoren wie x-data='{ open: false }' in einem solchen Setup gar nicht erst finden lassen, sondern stattdessen benannte Komponenten wie x-data='initMiniCart' verwendet werden.

Eine verbreitete Sorge ist, dass die restriktive Content-Security-Policy auch die eigenen Playwright-Skripte blockiert, sobald sie über page.evaluate() Code in die Seite einschleusen. Das trifft in der Praxis nicht zu, denn Chromium führt über das DevTools-Protokoll ausgeführten Code mit erweiterten Rechten außerhalb der regulären Skript-Pipeline aus, wodurch die CSP der Seite für Runtime.evaluate-Aufrufe nicht greift. Ein Test darf also frei introspizieren, obwohl die Seite selbst streng abgesichert ist.

5. Eine stabile data-testid-Konvention in Hyvä-Templates einführen

Hyvä-Templates liefern von Haus aus keine Test-Attribute, weshalb Tests entweder auf CSS-Klassen zurückgreifen, die für das Styling und nicht für die Testautomatisierung gedacht sind, oder auf Textinhalte, die sich zwischen der deutschen und der englischen Storeview unterscheiden. Eine eigene, sprachunabhängige data-testid-Konvention direkt in den .phtml-Overrides löst beide Probleme gleichzeitig und bleibt auch nach einem Tailwind-Refactoring stabil, das lediglich Utility-Klassen ändert.

Wichtig ist, die Konvention zentral zu dokumentieren, etwa als Namensschema aus Modul, Komponente und Aktion wie minicart-toggle oder filter-panel-apply, damit Teammitglieder nicht unabhängig voneinander eigene Muster erfinden. Da data-testid-Attribute reine HTML-Attribute ohne Skriptcharakter sind, haben sie keinerlei Auswirkung auf die Content-Security-Policy und können bedenkenlos direkt im produktiven Markup verbleiben.

6. Praxisbeispiel: den Mini-Cart-Dropdown zustandsbasiert testen

Am Beispiel des Mini-Cart-Dropdowns zeigt sich, wie Testid und Alpine-State im Zusammenspiel eine belastbare Assertion ergeben: Der Klick auf den Toggle-Button erfolgt über einen stabilen data-testid-Selektor, während die eigentliche Prüfung, ob das Dropdown geöffnet wurde und wie viele Artikel angezeigt werden, direkt gegen die Alpine-Eigenschaften open und itemCount läuft. Damit ist der Test unabhängig davon, ob das Dropdown per CSS-Transition ein- oder ausgeblendet wird.

Diese Kombination macht auch den Unterschied zwischen einem rein visuellen und einem funktionalen Fehler sichtbar: Bricht die Transition, meldet Playwright weiterhin einen offenen State, aber die Sichtbarkeitsprüfung schlägt fehl, sodass der Test präzise anzeigt, in welcher Schicht das Problem tatsächlich liegt, statt nur pauschal zu melden, dass irgendetwas nicht stimmt.

test('Mini-Cart zeigt die korrekte Artikelanzahl nach dem Hinzufuegen', async ({ page }) => {
  await page.goto('/rucksack-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 zwischen GraphQL-Antworten und Alpine-Rerendering

Ein Klick auf Warenkorb hinzufügen löst im Hyvä-Theme einen fetch-Aufruf gegen die GraphQL-API aus, dessen Antwort erst im Erfolgsfall die reaktive Alpine-Eigenschaft aktualisiert. Zwischen dem Auflösen des Promise und dem tatsächlichen DOM-Update liegt zusätzlich Alpines eigener Effekt-Scheduler, der Änderungen über einen Microtask bündelt, bevor er das DOM patcht. Ein Test, der direkt nach dem Klick assertet, sieht deshalb häufig noch den alten Zustand, obwohl der Klick technisch erfolgreich war.

Statt eine feste Wartezeit einzubauen, kombiniert man page.waitForResponse() für den GraphQL-Aufruf mit Playwrights automatisch wiederholenden Assertions wie expect(locator).toHaveText(), die intern so lange erneut prüfen, bis entweder der erwartete Wert erscheint oder ein Timeout erreicht wird. Diese Kombination bildet exakt die tatsächliche Reihenfolge aus Netzwerkantwort und reaktivem Rerendering ab, statt sie durch eine geratene Pause zu überbrücken.

8. Ein Page-Object-Pattern für Alpine-Komponenten aufbauen

Sobald mehrere Tests denselben Alpine-Selektor und dieselbe $data-Abfrage wiederholen, lohnt sich eine kleine Kapselung nach dem klassischen Page-Object-Muster, angepasst an Alpine-Zustand statt reiner DOM-Struktur. Eine Klasse wie MiniCart bündelt dann Methoden wie open(), isOpen() und itemCount(), sodass ein Test lesbar bleibt und interne Details wie den genauen x-data-Namen nur an einer einzigen Stelle im Projekt kennt.

Ändert sich später der Name der registrierten Alpine-Komponente, etwa weil ein Refactoring initMiniCart in useMiniCart umbenennt, muss nur das Page-Object angepasst werden, nicht jeder einzelne Test, der den Mini-Cart verwendet. Dieses Muster reduziert die Wartungslast einer wachsenden Testsuite erheblich und macht Alpine-State-Zugriffe zu einem wiederverwendbaren Baustein statt zu wiederholtem Boilerplate-Code.

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. Playwright-Tests stabil in die CI-Pipeline integrieren

In der CI-Pipeline sollte Playwright gegen eine dedizierte, mit Testdaten befüllte Hyvä-Instanz laufen, deren Katalog, Kundenkonten und Preise deterministisch sind, damit Assertions nicht von zufälligen Produktionsdaten abhängen. Retries auf Test-Ebene, etwa zwei Wiederholungen pro fehlgeschlagenem Test, fangen verbleibende Netzwerkschwankungen ab, ohne echte Regressionen zu verschleiern, solange die Retry-Rate im Report separat ausgewertet wird.

Für die Fehleranalyse lohnt sich, Traces nur beim ersten Retry aufzuzeichnen statt bei jedem Lauf, um Artefakt-Größe und Laufzeit im Rahmen zu halten, während im Fehlerfall trotzdem eine vollständige Zeitleiste mit Netzwerkaufrufen und DOM-Snapshots zur Verfügung steht. So bleibt die Pipeline schnell genug für den täglichen Einsatz und liefert im Ernstfall dennoch genug Kontext, um einen Fehler ohne lokale Reproduktion einzugrenzen.

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. Zusammenfassung

11. FAQ: Playwright und Alpine.js im Hyvä-Theme: Das Wichtigste auf einen Blick