Claude Code & Playwright: E2E-Tests automatisieren und debuggen

E2E-Tests schreiben kostet Zeit. Viel Zeit. Selektoren herausfinden, Wartezeiten kalibrieren, flaky Tests debuggen — das sind keine kreativen Aufgaben, aber sie fressen Entwicklerstunden. Playwright mit Claude Code macht daraus einen anderen Prozess: du beschreibst, was getestet werden soll, Claude Code schreibt den Test, du verifizierst und adjustierst.

Dieser Artikel zeigt den kompletten Weg: von der Wahl zwischen Playwright und Cypress, über Setup und Locators bis zu Page Object Model, Network Mocking und GitHub Actions Integration — alles mit konkreten Beispielen, die du direkt verwenden kannst.

1. Playwright vs. Cypress — Wann was?

Die Frage taucht in fast jedem Team auf, das erstmals E2E-Testing einführt. Beide Tools sind ausgereift, beide werden aktiv weiterentwickelt — aber sie haben unterschiedliche Stärken.

Playwright ist die bessere Wahl, wenn du mehrere Browser testen musst (Chromium, Firefox, WebKit), mobile Viewports brauchst, parallele Testläufe kritisch sind oder du in Python, Java oder C# arbeitest — Playwright unterstützt alle vier Sprachen nativ. Die Architektur ist moderner: Playwright kommuniziert direkt über das CDP-Protokoll und läuft in einem eigenen Prozess, was Isolation und Geschwindigkeit verbessert.

Cypress ist die bessere Wahl, wenn dein Team bereits in einem JavaScript-only-Stack lebt, du Time Travel Debugging schätzt und eine visuelle Test-Replay-Funktion direkt im Browser haben willst. Die Einrichtung für einfache Single-Page-Apps ist oft schneller.

• Multi-Browser-Abdeckung gefordert → Playwright
• Mobile Testing (iOS Safari Simulation) → Playwright
• TypeScript-Stack, maximale Parallelisierung → Playwright
• Einfache React-SPA, JavaScript-only-Team → Cypress ist vertretbar
• Backend-Tests (Python/Java/C#) → zwingend Playwright

Für neue Projekte empfehle ich heute Playwright als Standard. Die aktive Entwicklung, die breite Browser-Abdeckung und die native TypeScript-Unterstützung machen es zur robusteren Langzeitwahl.

2. Setup und Konfiguration mit Claude Code

Ein neues Playwright-Projekt einrichten dauert mit Claude Code wenige Minuten. Starte Claude Code aus dem Root-Verzeichnis deines Projekts und gib ihm den Kontext:

claude "Richte Playwright für dieses TypeScript-Projekt ein.
Tests sollen in tests/e2e/ liegen, Chromium und Firefox abdecken
und Screenshots bei Fehlern speichern."

Claude Code installiert das Package, generiert die playwright.config.ts und legt die Verzeichnisstruktur an. Die resultierende Config sieht typischerweise so aus:

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

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['github']],
  use: {
    baseURL: 'http://localhost:3000',
    screenshot: 'only-on-failure',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'mobile-safari', use: { ...devices['iPhone 14'] } },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

3. Locators: getByRole und getByText

Der häufigste Fehler beim Playwright-Einstieg: Tests die auf CSS-Selektoren oder XPath basieren. Diese Selektoren brechen bei jedem Layout-Refactoring — und sie testen nicht das, was der Nutzer sieht, sondern das, was im DOM steht.

Playwright-Locators gehen einen anderen Weg: sie spiegeln, wie ein Mensch (oder ein Screenreader) die Seite wahrnimmt.

// Fragil — bricht bei CSS-Änderungen
await page.click('.btn-primary.submit-button');

// Robust — orientiert sich an semantischer Rolle
await page.getByRole('button', { name: 'Jetzt kaufen' }).click();

// Text-basiert für Labels und Inhalte
await page.getByText('Bestellung erfolgreich').waitFor();

// Placeholder für Formularfelder
await page.getByPlaceholder('E-Mail-Adresse').fill('test@example.com');

// Label-Text für Inputs
await page.getByLabel('Passwort').fill('sicher123');

Claude Code kennt diese Hierarchie und verwendet sie automatisch, wenn du einen Test beschreibst. Der Vorteil: Tests, die Claude Code mit Rolle-basierten Locators schreibt, sind gleichzeitig Barrierefreiheits-Tests — wenn getByRole einen Button nicht findet, fehlt dem Element das korrekte ARIA-Attribut.

4. Assertions

Playwright hat eine eigene Assertion-Bibliothek die auf automatisches Warten ausgelegt ist — kein manuelles waitFor nötig für den Normalfall:

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

// Element sichtbar?
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();

// Text vorhanden?
await expect(page.getByTestId('status-badge')).toHaveText('Aktiv');

// URL nach Navigation?
await expect(page).toHaveURL('/dashboard/');

// Formularfeld gefüllt?
await expect(page.getByLabel('Name')).toHaveValue('Max Mustermann');

// Element nicht vorhanden?
await expect(page.getByRole('alert')).not.toBeVisible();

Alle expect()-Assertions warten automatisch bis zu 5 Sekunden (konfigurierbar) auf das erwartete Ergebnis. Das eliminiert die früher üblichen await page.waitForTimeout(1000)-Zeilen, die Tests langsam und unzuverlässig machen.

5. Page Object Model

Sobald mehr als drei Tests dieselbe Seite verwenden, zahlt sich das Page Object Model aus. Es kapselt Selektoren und Aktionen in einer Klasse — ändert sich die UI, muss nur die Page Object-Klasse angepasst werden, nicht jeder einzelne Test.

Claude Code generiert Page Objects auf Zuruf:

claude "Erstelle ein Page Object für die Login-Seite unserer App.
Sie hat Email-Feld, Passwort-Feld, Submit-Button und
einen Fehlertext bei falschen Credentials."

Das Ergebnis:

import { Page, Locator } from '@playwright/test';

export class LoginPage {
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(private page: Page) {
    this.emailInput = page.getByLabel('E-Mail');
    this.passwordInput = page.getByLabel('Passwort');
    this.submitButton = page.getByRole('button', { name: 'Anmelden' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}

// Verwendung im Test:
const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login('user@example.com', 'passwort123');
await expect(page).toHaveURL('/dashboard/');

6. Screenshots und Traces

Wenn ein E2E-Test in CI fehlschlägt, braucht man Beweise: was war auf der Seite zu sehen, welche Aktionen wurden ausgeführt, wo ist es schiefgelaufen. Playwright liefert zwei Werkzeuge dafür.

Screenshots werden automatisch bei Fehlern gespeichert (wenn screenshot: 'only-on-failure' in der Config steht). Du kannst sie auch manuell setzen:

// Screenshot an einem bestimmten Punkt
await page.screenshot({ path: 'screenshots/nach-login.png', fullPage: true });

// Screenshot bei einem Assertion-Fehler wird automatisch gespeichert

Traces gehen weiter: Sie zeichnen jeden Schritt auf — Netzwerkanfragen, DOM-Zustände, Konsolenausgaben, Screenshots pro Aktion. Mit trace: 'on-first-retry' wird ein Trace nur bei einem Retry aufgezeichnet, was CI-Laufzeit spart.

# Trace ansehen (nach einem fehlgeschlagenen Testlauf)
npx playwright show-trace test-results/mein-test/trace.zip

Der Trace Viewer ist eine vollständige Wiederholung des Testlaufs im Browser — du siehst jeden Klick, jeden Request, jeden DOM-Zustand. Claude Code kann einen Trace-Pfad analysieren, wenn du ihm die Ausgabe übergibst.

7. Network Interception — APIs mocken

E2E-Tests die echte APIs aufrufen sind langsam, fragil und schwer zu kontrollieren. Playwright's route()-API lösst das: Anfragen abfangen, durch Mock-Antworten ersetzen, Fehler simulieren.

test('zeigt Fehlermeldung bei API-Ausfall', async ({ page }) => {
  // API-Aufruf abfangen und 500 zurückgeben
  await page.route('**/api/products', route => route.fulfill({
    status: 500,
    body: JSON.stringify({ error: 'Internal Server Error' }),
  }));

  await page.goto('/shop');
  await expect(page.getByRole('alert')).toContainText('Produkte konnten nicht geladen werden');
});

test('zeigt Produktliste mit Mock-Daten', async ({ page }) => {
  await page.route('**/api/products', route => route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify([
      { id: 1, name: 'Testprodukt', price: 29.99 },
    ]),
  }));

  await page.goto('/shop');
  await expect(page.getByText('Testprodukt')).toBeVisible();
});

8. Mobile Testing

Playwright simuliert mobile Geräte vollständig: Viewport, Touch-Events, User-Agent, Netzwerkdrosselung. Kein separates Tool nötig.

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

test.use({ ...devices['iPhone 14'] });

test('Mobile Navigation funktioniert', async ({ page }) => {
  await page.goto('/');

  // Hamburger-Menü auf Mobile
  await page.getByRole('button', { name: 'Menü öffnen' }).tap();
  await expect(page.getByRole('navigation')).toBeVisible();

  // Touch-Scroll
  await page.locator('.product-carousel').evaluate(el => {
    el.scrollLeft += 300;
  });
});

In der playwright.config.ts kannst du mobile Geräte als eigene Projects definieren (wie im Setup-Beispiel oben gezeigt). Damit laufen alle Tests automatisch auch gegen mobile Viewports — ohne Code-Duplikation.

9. GitHub Actions Integration

Playwright in CI einzubinden ist einer der häufigsten Punkte, bei dem Teams Zeit verlieren. Claude Code kann das komplett automatisieren:

claude "Erstelle eine GitHub Actions Workflow-Datei für Playwright-Tests.
Tests sollen bei jedem PR laufen, Artefakte (Screenshots, Traces)
sollen hochgeladen werden und der Playwright HTML Report soll
als GitHub Pages Deployment bereitgestellt werden."

Das generierte Workflow-File:

name: E2E Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Der if: always() beim Artefakt-Upload stellt sicher, dass Screenshots und Traces auch bei fehlgeschlagenen Tests hochgeladen werden — genau dann, wenn du sie brauchst.

Zwei verwandte Artikel die den Workflow ergänzen:

• Claude Code Debugging — Bugs systematisch finden, Stack Traces analysieren, Root-Cause vor Quickfix
• Claude Code & GitHub Actions — vollständige CI/CD-Pipelines mit Claude Code aufbauen