Responsive Breakpoints systematisch testen

1. Warum Breakpoint-Tests nicht bei jedem Pixel ansetzen sollten

Ein weit verbreiteter Irrglaube beim responsiven Testen lautet, dass man möglichst viele Viewport-Breiten prüfen muss, um sicherzugehen. In der Praxis führt das zu Testsuiten, die 320px, 375px, 414px, 480px, 600px, 768px, 900px, 1024px und ein Dutzend weiterer Breiten iterieren, obwohl sich das Layout zwischen den meisten davon überhaupt nicht verändert. Jede zusätzliche Viewport-Breite kostet CI-Laufzeit, ohne zusätzliche Aussagekraft zu liefern, solange sich zwischen zwei Breiten keine einzige CSS-Regel ändert.

Relevant sind ausschließlich die Breiten, an denen sich das Layout tatsächlich ändert, also genau die Breakpoints, die im Tailwind-Design-System als sm, md, lg und xl definiert sind. Alles zwischen zwei Breakpoints verhält sich CSS-technisch identisch, weil Tailwind-Utilities wie md:grid-cols-3 erst exakt am definierten Schwellenwert greifen. Wer diesen Zusammenhang verstanden hat, reduziert die Anzahl nötiger Testläufe drastisch und konzentriert die verbleibende Testzeit auf die Stellen, an denen tatsächlich Bugs entstehen können.

2. Die relevanten Breakpoints aus dem Design System ableiten

Der erste Schritt jeder systematischen Breakpoint-Teststrategie ist, die tatsächlich verwendeten Schwellenwerte aus der Konfiguration auszulesen, statt sie aus Erfahrung zu schätzen. In Tailwind CSS v4 werden Breakpoints im CSS-first Ansatz über @theme mit benannten --breakpoint-*-Variablen definiert, nicht mehr zwingend in einer separaten tailwind.config.js. Diese Werte sind die einzige verbindliche Quelle: Jeder Test, der eigene Breitenwerte erfindet, testet am eigentlichen Design-System vorbei.

In einem Hyvä-Theme lohnt es sich, die effektiven Breakpoint-Werte einmalig in eine zentrale Testkonfiguration zu exportieren, etwa als JSON- oder JS-Objekt, das sowohl von Cypress- als auch von Playwright-Specs importiert wird. So bleibt die Testsuite automatisch synchron, wenn im Design-System ein Breakpoint verschoben wird, statt dass Breitenwerte doppelt gepflegt werden und irgendwann inkonsistent sind. Ein einzelner geänderter Wert in der zentralen Konfiguration aktualisiert dann alle betroffenen Testfälle automatisch.

/* app/design/frontend/Mironsoft/default/web/tailwind/tailwind-source.css */
@theme {
  /* Named breakpoints - single source of truth for the design system */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
}

/* Export the same values as JSON for Cypress/Playwright to import,
   generated once via a small build script, never hand-copied. */

3. Boundary-Testing: knapp über und unter dem Schwellenwert

Die meisten Layout-Bugs an Breakpoints sind klassische Off-by-One-Fehler: Ein md:-Präfix in Tailwind greift ab 768px einschließlich, nicht erst ab 769px. Wer nur bei exakt 768px oder nur mittig zwischen zwei Breakpoints testet, übersieht genau die Fälle, in denen ein Entwickler max-width: 767px statt max-width: 768px in einer Media Query geschrieben hat oder ein zusätzliches CSS-Framework mit einer abweichenden Konvention kollidiert.

Das robuste Boundary-Testing-Pattern prüft daher immer drei Punkte pro Breakpoint: einen Pixel unterhalb des Schwellenwerts, exakt am Schwellenwert und einen Pixel oberhalb. Bei einem md-Breakpoint von 768px bedeutet das konkret Tests bei 767px, 768px und 769px. Nur so lässt sich zuverlässig nachweisen, dass der Layoutwechsel exakt an der erwarteten Stelle passiert und nicht einen oder mehrere Pixel daneben liegt, was insbesondere bei verschachtelten Media Queries schnell passiert.

4. Breakpoint-Iteration mit Cypress

Cypress bietet mit cy.viewport(width, height) die direkte Möglichkeit, die Viewport-Größe innerhalb eines Tests zu verändern. Für systematisches Breakpoint-Testing iteriert man über ein Array der relevanten Breakpoints und führt für jeden Eintrag dieselbe Testlogik aus, statt für jede Breite eine eigene it()-Definition zu duplizieren. Das hält die Testsuite wartbar, auch wenn später ein weiterer Breakpoint ergänzt wird.

Wichtig ist, nach jedem cy.viewport()-Aufruf kurz zu warten oder auf ein stabiles DOM-Element zu prüfen, bevor Assertions laufen, da CSS-Transitions und Reflow-Berechnungen nicht synchron mit dem Viewport-Wechsel abgeschlossen sind. Cypress führt Tests standardmäßig in einem einzigen Browser-Fenster aus, weshalb die Viewport-Änderung sehr schnell ist. Für echte Cross-Browser-Absicherung sollte dieselbe Teststruktur zusätzlich in Firefox und WebKit über die entsprechenden Cypress-Browser-Launcher laufen.

// cypress/e2e/responsive/breakpoints.cy.js
// Single source of truth, mirrors the Tailwind @theme breakpoint values
const breakpoints = [
  { name: 'sm', width: 640 },
  { name: 'md', width: 768 },
  { name: 'lg', width: 1024 },
  { name: 'xl', width: 1280 },
];

describe('Product grid across breakpoints', () => {
  breakpoints.forEach(({ name, width }) => {
    it(`renders a valid grid layout at ${name} (${width}px)`, () => {
      cy.viewport(width, 900);
      cy.visit('/catalog/category/view/id/23');

      // Let CSS transitions and reflow settle before asserting
      cy.get('[data-testid="product-grid"]').should('be.visible');
      cy.get('[data-testid="product-card"]').should('have.length.greaterThan', 0);
    });
  });
});

5. Breakpoint-Iteration mit Playwright

Playwright setzt Viewport-Größen über page.setViewportSize() oder direkt beim Erzeugen eines neuen BrowserContext mit der viewport-Option. Der entscheidende Vorteil gegenüber Cypress liegt in der nativen Parallelisierung: Mehrere Breakpoints lassen sich über Playwrights test.describe.parallel() oder über separate Projekte in der playwright.config.ts gleichzeitig statt nacheinander ausführen, was die Gesamtlaufzeit einer Breakpoint-Matrix deutlich reduziert.

Für Boundary-Tests bietet sich eine parametrisierte Testfunktion an, die sowohl die Breakpoint-Liste aus der zentralen Design-System-Konfiguration als auch den Delta-Wert von einem Pixel als Parameter erhält. Playwrights eingebaute toHaveScreenshot()-Assertion eignet sich zusätzlich hervorragend, um bei jedem Boundary-Test einen Screenshot-Vergleich anzustoßen und so nicht nur strukturelle, sondern auch rein visuelle Regressionen an der Breakpoint-Grenze zu erkennen.

// tests/responsive/breakpoint-boundaries.spec.ts
import { test, expect } from '@playwright/test';

// Mirrors the Tailwind @theme breakpoint values, single source of truth
const mdBreakpoint = 768;
const deltas = [-1, 0, 1];

for (const delta of deltas) {
  const width = mdBreakpoint + delta;

  test(`navigation state at ${width}px (md boundary ${delta})`, async ({ page }) => {
    await page.setViewportSize({ width, height: 900 });
    await page.goto('/');

    const isDesktopNav = width >= mdBreakpoint;
    const mobileToggle = page.getByTestId('nav-mobile-toggle');
    const desktopNav = page.getByTestId('nav-desktop');

    if (isDesktopNav) {
      await expect(desktopNav).toBeVisible();
      await expect(mobileToggle).toBeHidden();
    } else {
      await expect(mobileToggle).toBeVisible();
      await expect(desktopNav).toBeHidden();
    }
  });
}

6. Content-Reflow und Element-Overlap erkennen

Ein Breakpoint-Wechsel kann zwei unterschiedliche Bug-Klassen auslösen: unerwarteten Content-Reflow, bei dem Text plötzlich abgeschnitten wird oder Elemente außerhalb des sichtbaren Bereichs landen, und Element-Overlap, bei dem zwei eigentlich getrennte Elemente sich überlappen, weil eine Breite oder ein Margin-Wert nicht für die neue Spaltenzahl angepasst wurde. Beide Fehlerklassen sind mit reinen Snapshot-Vergleichen nur teilweise erkennbar, weil kleine Pixelverschiebungen oft als False Positive markiert werden.

Zuverlässiger ist eine Kombination aus getBoundingClientRect()-Abfragen für alle relevanten Elemente und einer einfachen Overlap-Berechnung, die prüft, ob sich zwei Bounding-Boxen rechnerisch schneiden. Für Content-Reflow prüft man zusätzlich scrollWidth gegen clientWidth eines Containers. Weicht der Wert ab, liegt horizontaler Overflow vor, der auf mobilen Breakpoints fast immer ein Bug ist. Diese Prüfungen lassen sich als wiederverwendbare Helper-Funktion in beiden Frameworks einsetzen.

// tests/support/reflow-helpers.ts
// Detects horizontal overflow and overlapping elements at a given viewport
export async function detectReflowIssues(page) {
  return page.evaluate(() => {
    const issues = [];
    const container = document.querySelector('[data-testid="product-grid"]');

    if (container && container.scrollWidth > container.clientWidth + 1) {
      issues.push(`Horizontal overflow: scrollWidth ${container.scrollWidth} > clientWidth ${container.clientWidth}`);
    }

    const cards = Array.from(document.querySelectorAll('[data-testid="product-card"]'));
    const rects = cards.map((el) => el.getBoundingClientRect());

    for (let i = 0; i < rects.length; i++) {
      for (let j = i + 1; j < rects.length; j++) {
        const a = rects[i];
        const b = rects[j];
        const overlaps = a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
        if (overlaps) {
          issues.push(`Card ${i} overlaps card ${j}`);
        }
      }
    }

    return issues;
  });
}

7. Navigation: Hamburger- zu Vollmenü-Übergang testen

Der Wechsel von einer Hamburger-Navigation zur vollständigen Desktop-Navigation ist einer der häufigsten und gleichzeitig am schlechtesten getesteten Breakpoint-Übergänge in Hyvä-Themes. Typische Bugs: Das Hamburger-Icon bleibt eine Pixelbreite zu lange sichtbar und überlappt mit der einblendenden Desktop-Navigation, oder das Untermenü eines Dropdown-Punkts öffnet sich nach dem Wechsel noch im mobilen Overlay-Stil statt als Desktop-Flyout.

Ein robuster Test prüft an der exakten Breakpoint-Grenze via cy.get() beziehungsweise page.locator(), dass genau eines der beiden Navigationselemente sichtbar ist, niemals beide gleichzeitig und niemals keines. Zusätzlich lohnt sich ein Klick-Test direkt an der Grenze: Öffnet die mobile Navigation bei 767px korrekt als Alpine.js-Overlay, und ist bei 768px stattdessen die Desktop-Navigation ohne Overlay klickbar? Diese Interaktionsebene deckt Bugs auf, die eine reine Sichtbarkeitsprüfung übersieht.

8. Produktraster: Spaltenzahl-Wechsel verifizieren

Produktlisten sind ein weiterer Breakpoint-Hotspot, weil sich die Grid-Spaltenzahl in Hyvä-Shops typischerweise mehrfach ändert: zwei Spalten auf Mobile, drei auf Tablet, vier auf Desktop. Ein häufiger Bug entsteht, wenn grid-cols-2, md:grid-cols-3 und lg:grid-cols-4 zwar korrekt gesetzt sind, aber ein einzelnes Produktkarten-Element eine feste min-width trägt, die bei drei Spalten nicht mehr in die verfügbare Breite passt und dadurch umbricht.

Der zuverlässigste Test zählt nicht CSS-Klassen, sondern die tatsächlich gerenderte Position der Produktkarten: Karten mit identischer offsetTop-Position gehören zur selben Zeile, ihre Anzahl entspricht der erwarteten Spaltenzahl. Diese Prüfung funktioniert unabhängig davon, ob das Grid über CSS Grid, Flexbox oder Tailwind-Utilities umgesetzt ist, und erkennt zuverlässig, wenn eine Karte durch fehlerhaftes Wrapping in eine falsche Zeile rutscht, ein Bug, der in einem reinen Klassennamen-Check unsichtbar bliebe.

9. Naiver vs. systematischer Ansatz im Vergleich

Der Unterschied zwischen einer wahllosen Breitenliste und einer systematischen Breakpoint-Boundary-Strategie zeigt sich am deutlichsten im direkten Vergleich, sowohl bei der CI-Laufzeit als auch bei der tatsächlichen Fehlererkennungsrate. Die folgende Tabelle stellt beide Ansätze entlang der wichtigsten Testdimensionen gegenüber.

In der Praxis zeigt sich, dass die systematische Variante trotz deutlich weniger Testläufen mehr echte Bugs findet, weil sie exakt dort ansetzt, wo Layoutwechsel stattfinden. Teams, die von der willkürlichen Breitenliste auf Boundary-Testing umstellen, reduzieren ihre CI-Laufzeit für Responsive-Tests häufig um 60 bis 70 Prozent, ohne Abstriche bei der Testabdeckung der eigentlich kritischen Übergänge.

# .github/workflows/responsive-breakpoints.yml
name: Responsive Breakpoint Tests
on: [pull_request]

jobs:
  breakpoint-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        breakpoint:
          - { name: sm, width: 640 }
          - { name: md, width: 768 }
          - { name: lg, width: 1024 }
          - { name: xl, width: 1280 }
        delta: [-1, 0, 1]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: Run boundary tests for ${{ matrix.breakpoint.name }} (${{ matrix.delta }}px)
        run: >
          npx playwright test tests/responsive/breakpoint-boundaries.spec.ts
          --grep "${{ matrix.breakpoint.name }} boundary ${{ matrix.delta }}"
        env:
          BREAKPOINT_WIDTH: ${{ matrix.breakpoint.width }}
          BREAKPOINT_DELTA: ${{ matrix.delta }}

10. Zusammenfassung

Systematisches Breakpoint-Testing löst ein einfaches, aber teures Problem: Wer wahllos Viewport-Breiten durchprobiert, verschwendet CI-Zeit und übersieht trotzdem die Stellen, an denen tatsächlich Bugs entstehen. Relevant sind nur die Breiten, die im Tailwind-Design-System als sm, md, lg und xl definiert sind, und dort speziell die drei Punkte direkt an jeder Grenze: ein Pixel darunter, exakt am Schwellenwert und ein Pixel darüber. Genau dort verstecken sich die Off-by-One-Fehler, die zwischen zwei Breakpoints niemals auftreten können.

Cypress und Playwright bieten beide direkte APIs für Viewport-Steuerung, Playwright zusätzlich native Parallelisierung für größere Breakpoint-Matrizen. Kombiniert mit gezielten Prüfungen für Content-Reflow, Element-Overlap, Navigation-Übergänge und Grid-Spaltenzahl entsteht eine Testsuite, die deutlich weniger Läufe braucht als eine willkürliche Breitenliste und trotzdem mehr echte Layout-Bugs findet. In einer CI-Pipeline als Breakpoint-Matrix organisiert, bleibt diese Absicherung auch bei wachsendem Design-System wartbar.

11. FAQ: Responsive Breakpoints systematisch testen