Playwright Setup und Grundlagen im Vergleich zu Cypress

1. Playwright und Cypress: zwei Wege zum gleichen Ziel

Wer heute ein neues Frontend-Projekt gegen Fehlerregressionen absichern will, landet fast zwangsläufig bei zwei Namen: Cypress und Playwright. Beide Frameworks lösen dieselbe Grundaufgabe, echte Nutzerinteraktionen in einem echten Browser zu simulieren, und decken damit mehr ab, als ein reiner PHPUnit-Test auf Klassenebene jemals könnte. Der Unterschied liegt nicht in der grundsätzlichen Idee, sondern in der Architektur darunter: wie Tests den Browser steuern, welche Browser-Engines unterstützt werden und wie Teams Fehlschläge in der CI-Pipeline diagnostizieren.

Für Magento- und Hyvä-Projekte ist diese Entscheidung besonders relevant, weil Storefronts mit Alpine.js-Interaktionen, Warenkorb-Updates und Checkout-Flows viele asynchrone Zustände durchlaufen, die ein Unit-Test nicht erfasst. Dieser Artikel zeigt die Installation von Playwright, die wichtigsten Konfigurationsoptionen und einen ersten echten Test gegen einen Storefront, bevor am Ende ein direkter Vergleich mit Cypress bei der Framework-Wahl hilft.

2. Playwright installieren: npm init playwright@latest im Detail

Die Installation von Playwright startet mit einem einzigen Befehl: npm init playwright@latest. Das CLI-Tool fragt interaktiv ab, ob TypeScript oder JavaScript verwendet werden soll, wie das Testverzeichnis heißen soll (Standard: tests), ob eine GitHub-Actions-Workflow-Datei angelegt werden soll und ob die Browser-Binaries direkt heruntergeladen werden sollen. Im Gegensatz zu Cypress, das beim ersten Start eine grafische Setup-Oberfläche öffnet, bleibt Playwright vollständig im Terminal und erzeugt alle Dateien ohne manuellen Zwischenschritt.

Nach Abschluss liegt ein lauffähiges Grundgerüst vor: playwright.config.ts im Projekt-Root, ein tests-Ordner mit einem Beispieltest, ein tests-examples-Ordner mit didaktischen Referenztests und die passenden package.json-Skripte. Der Befehl npx playwright install lädt zusätzlich die drei Browser-Engines Chromium, Firefox und WebKit als eigenständige Binaries herunter, komplett unabhängig vom lokal installierten Chrome oder Firefox. Das macht CI-Umgebungen deterministisch, weil jede Pipeline exakt dieselbe Browser-Version nutzt statt der zufällig vorinstallierten Systemversion.

# Install Playwright in a new or existing Node.js project
npm init playwright@latest

# CLI prompts (interactive):
#   - TypeScript or JavaScript?          -> TypeScript
#   - Tests folder name?                 -> tests
#   - Add a GitHub Actions workflow?     -> Yes
#   - Install Playwright browsers now?   -> Yes

# Download all three browser engines as standalone binaries
npx playwright install --with-deps

3. Anatomie der playwright.config.ts

Die zentrale Konfigurationsdatei playwright.config.ts ist ein einziges TypeScript-Objekt mit klar getrennten Verantwortlichkeiten. Das projects-Array definiert, gegen welche Browser-Engines dieselbe Testsuite läuft, üblicherweise je ein Eintrag für Chromium, Firefox und WebKit mit den passenden devices-Voreinstellungen aus @playwright/test. Der use-Block setzt globale Defaults wie baseURL, trace, screenshot und video, die von allen Projekten geerbt und pro Projekt überschrieben werden können.

Reporter werden über das reporter-Feld konfiguriert, üblich ist eine Kombination aus html für die lokale Auswertung und github oder junit für die CI-Integration. Zusätzlich steuern timeout, retries und fullyParallel das Laufzeitverhalten der gesamten Suite zentral an einer Stelle. Cypress kennt mit cypress.config.ts ein vergleichbares Konzept, dort fehlt jedoch das native projects-Array für Multi-Browser-Läufe. Browser-Varianten müssen in Cypress stattdessen über separate CLI-Aufrufe mit dem Flag --browser gestartet werden.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: [['html'], ['github']],

  use: {
    baseURL: 'https://storefront.mironsoft-shop.test',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  // Same test suite runs against all three engines
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

4. Multi-Browser als Standard: Chromium, Firefox und WebKit

Der strukturell größte Unterschied zwischen beiden Frameworks zeigt sich beim Browser-Support. Playwright liefert mit Chromium, Firefox und WebKit drei vollständig unterstützte Engines aus einer einzigen Installation, und WebKit ist die Engine hinter Safari, die einzige praktikable Möglichkeit, Safari-Rendering ohne echtes Apple-Gerät in CI zu testen. Alle drei Engines laufen als eigenständige Browser-Builds, die Playwright selbst verwaltet und patcht, unabhängig von Betriebssystem-Updates.

Cypress hingegen ist historisch auf die Chromium-Familie fokussiert: Chrome, Edge und die eigene Electron-Runtime laufen stabil und mit vollem Feature-Set. Firefox-Support existiert seit Cypress 4, gilt aber als weniger ausgereift und deckt nicht alle Kommandos identisch ab. Eine WebKit- oder Safari-Engine bietet Cypress nicht an, ein experimentelles WebKit-Paket wurde 2023 wieder eingestellt. Für Projekte, die Safari-Nutzer ernsthaft absichern müssen, etwa weil ein relevanter Anteil des Magento-Traffics von iOS-Geräten kommt, ist Playwright deshalb häufig die naheliegendere Wahl.

5. Locators, Auto-Waiting und isolierte Browser-Kontexte

Playwright steuert Browser über das Chrome DevTools Protocol beziehungsweise das browserübergreifende WebDriver-BiDi-Protokoll von außen, statt sich wie Cypress direkt in den Browser-Prozess einzuklinken. Das ermöglicht echte Browser-Kontexte: Jeder Test kann in einem frischen, isolierten Kontext mit eigenen Cookies, eigenem LocalStorage und eigener Session laufen, vergleichbar mit einem neuen Inkognito-Fenster, ohne dass dafür ein komplett neuer Browser-Prozess gestartet werden muss.

Die Locator-API von Playwright wartet automatisch, bis ein Element sichtbar, aktiviert und stabil ist, bevor eine Aktion ausgeführt wird, ganz ohne explizite waitFor-Aufrufe im Testcode. Cypress verfolgt einen ähnlichen Grundgedanken mit automatischem Retry auf Assertions, läuft aber als Skript innerhalb des Browsers selbst, was Cross-Origin-Navigation traditionell erschwert hat. Seit cy.origin() unterstützt auch Cypress Multi-Domain-Flows, der Umweg über einen expliziten Befehl bleibt aber im Vergleich zu Playwrights nahtloser page.goto()-Navigation über beliebige Domains spürbar.

6. Erster Test: Add-to-Cart-Flow im Hyvä-Storefront

Ein realistischer erster Test prüft den zentralen Conversion-Pfad eines Magento-Shops: ein Produkt öffnen, in den Warenkorb legen und die aktualisierte Warenkorb-Anzeige verifizieren. In Playwright beginnt ein solcher Test mit page.goto() auf die relative Produkt-URL, aufbauend auf der baseURL aus der Konfiguration. Elemente werden über page.getByRole() oder page.getByTestId() angesprochen, semantische Selektoren, die robuster gegen CSS-Refactorings sind als klassische CSS-Klassen-Selektoren.

Nach dem Klick auf den Add-to-Cart-Button prüft expect(locator).toBeVisible() beziehungsweise toHaveText(), ob sich der Mini-Cart-Zähler im Hyvä-Header tatsächlich aktualisiert hat, inklusive automatischem Warten auf die Alpine.js-getriebene UI-Aktualisierung. Der komplette Test läuft mit npx playwright test add-to-cart.spec.ts gegen alle in der Konfiguration definierten Browser-Projekte gleichzeitig, ohne dass der Testcode selbst irgendetwas von der Multi-Browser-Ausführung wissen muss.

import { test, expect } from '@playwright/test';

test.describe('Storefront add-to-cart flow', () => {
  test('adds a product and updates the mini cart', async ({ page }) => {
    // baseURL comes from playwright.config.ts, no need to repeat the host
    await page.goto('/catalog/product/example-hoodie.html');

    // Semantic locator instead of a brittle CSS class selector
    await page.getByRole('button', { name: 'In den Warenkorb' }).click();

    // Auto-waits for the Alpine.js driven mini-cart update
    const miniCartCount = page.getByTestId('minicart-counter');
    await expect(miniCartCount).toHaveText('1');
    await expect(page.getByText('Zum Warenkorb hinzugefügt')).toBeVisible();
  });
});

7. Trace Viewer und UI Mode: eingebautes Debugging

Ein fehlschlagender Test in der CI-Pipeline ist ohne guten Kontext schwer zu diagnostizieren. Playwrights Trace Viewer zeichnet bei trace: 'on-first-retry' eine vollständige Aufzeichnung des Testlaufs auf: DOM-Snapshots vor und nach jeder Aktion, Netzwerk-Requests, Konsolen-Logs und Screenshots, alles in einer einzigen .zip-Datei. Mit npx playwright show-trace trace.zip öffnet sich eine Zeitleiste, durch die man Frame für Frame navigieren kann, ganz ohne den Test lokal erneut auszuführen.

Für die lokale Entwicklung bietet der UI Mode (npx playwright test --ui) eine interaktive Oberfläche mit Watch-Modus, Zeitleiste und Pick-Locator-Werkzeug. Cypress war mit seinem Test Runner und dem Time-Travel-Debugging einer der Pioniere in diesem Bereich und bietet ebenfalls eine exzellente lokale Entwickler-Erfahrung. Der entscheidende Unterschied liegt im CI-Fall: Cypress-Traces in dieser Tiefe erfordern Cypress Cloud als kostenpflichtigen Dienst, während Playwrights Trace Viewer vollständig lokal und kostenlos funktioniert.

8. Parallelisierung und das Worker-Modell

Playwright verteilt Testdateien standardmäßig auf mehrere Worker-Prozesse, deren Anzahl sich an den verfügbaren CPU-Kernen orientiert und über workers in der Konfiguration oder das CLI-Flag --workers=4 gezielt gesteuert werden kann. Mit fullyParallel: true lassen sich sogar einzelne Tests innerhalb derselben Datei parallel ausführen, statt nur datei-übergreifend. Für große CI-Pipelines unterstützt Playwright zusätzlich Sharding über --shard=1/4, wodurch eine Testsuite auf mehrere CI-Maschinen aufgeteilt wird, jede Maschine bearbeitet nur ihren Anteil.

Cypress führt Tests standardmäßig seriell innerhalb einer einzigen Browser-Instanz aus. Echte Parallelisierung über mehrere Maschinen hinweg erfordert Cypress Cloud oder eine Drittanbieter-Orchestrierung, die Testdateien manuell auf CI-Runner verteilt. Für Teams mit begrenztem Budget bedeutet das: Playwrights Worker- und Sharding-Modell liefert kostenlos eingebaute Parallelisierung, während vergleichbare Cypress-Geschwindigkeit in der Regel zusätzliche Lizenzkosten oder Eigenbau-Infrastruktur voraussetzt.

{
  "scripts": {
    "test": "playwright test",
    "test:ui": "playwright test --ui",
    "test:debug": "playwright test --debug",
    "test:report": "playwright show-report",
    "test:chromium": "playwright test --project=chromium"
  }
}

9. Cypress oder Playwright: Entscheidungsrahmen für neue Projekte

Die Wahl zwischen Cypress und Playwright hängt selten von einem einzelnen Kriterium ab, sondern von einer Kombination aus Team-Skillset, Browser-Abdeckung und CI-Budget. Teams mit reiner JavaScript/TypeScript-Erfahrung und Fokus auf Chrome-Nutzer sind mit Cypress oft schneller produktiv, weil Dokumentation und Community-Beispiele seit Jahren ausgereift sind. Sobald jedoch Safari-Traffic relevant ist, mehrere Programmiersprachen im Team existieren oder CI-Parallelisierung ohne Zusatzkosten gefordert ist, verschiebt sich die Entscheidung strukturell in Richtung Playwright.

Für neue Magento- und Hyvä-Projekte empfiehlt sich Playwright zusätzlich, weil Storefronts von einem breiten Gerätemix aus Desktop, Mobile Safari und Android Chrome besucht werden und ein einzelnes Test-Setup alle drei Engines abdecken soll. Die folgende Tabelle fasst die wichtigsten Entscheidungskriterien direkt gegenüber.

# Run the full suite against every configured browser project
npx playwright test

# Run only against Chromium during local development
npx playwright test --project=chromium --headed

# Split the suite across 4 CI machines (shard 1 of 4)
npx playwright test --shard=1/4

# Open the last recorded trace for a failed test
npx playwright show-trace trace.zip

In der Praxis entscheidet selten ein einzelnes Kriterium allein: Ein Team mit reinem Chrome-Fokus und bestehender Cypress-Erfahrung profitiert wenig von einem Wechsel, während ein neues Projekt mit Safari-Traffic, knappem CI-Budget und dem Wunsch nach mehrsprachigen Testautoren mit Playwright strukturell besser aufgestellt ist.

10. Zusammenfassung

Playwright und Cypress lösen beide die Aufgabe, echte Nutzerflüsse in einem echten Browser abzusichern, unterscheiden sich aber fundamental in der Architektur. Playwright installiert sich über einen einzigen CLI-Befehl, bringt mit Chromium, Firefox und WebKit drei vollständig unterstützte Browser-Engines mit und steuert sie extern über ein Protokoll statt als eingebettetes Skript im Browser selbst. Die playwright.config.ts bündelt Projekte, globale Defaults und Reporter an einer zentralen Stelle, und der native Worker- sowie Sharding-Mechanismus parallelisiert Testläufe ohne zusätzliche Lizenzkosten.

Cypress bleibt für Teams mit reinem Chrome-Fokus und etablierten Workflows eine solide Wahl, besonders dank seines ausgereiften Time-Travel-Debuggings im Test Runner. Sobald jedoch Safari-Abdeckung, Mehrsprachigkeit im Team oder kostenlose CI-Parallelisierung gefordert sind, liefert Playwright die strukturell passenderen Werkzeuge. Für neue Magento- und Hyvä-Projekte mit breitem Gerätemix ist Playwright deshalb häufig der robustere Ausgangspunkt.

11. FAQ: Playwright Setup und Grundlagen im Vergleich zu Cypress