Component Testing mit Cypress statt nur E2E

1. Component Testing vs. E2E: Was cy.mount() wirklich testet

Cypress kennt seit Version 10 zwei grundlegend unterschiedliche Testarten: E2E-Tests, die eine komplette Seite über eine echte URL im Browser aufrufen, und Component Tests, die mit cy.mount() eine einzelne Komponente isoliert in einem minimalen Test-Wrapper rendern. Der Unterschied ist mehr als eine technische Konfiguration: Ein E2E-Test gegen eine Hyvä-Checkout-Seite lädt Magento, Session, Warenkorb-API und das komplette Theme, bevor überhaupt eine Assertion läuft. Ein Component Test für dieselbe Mengenauswahl-Komponente lädt ausschließlich deren HTML-Markup und das zugehörige Alpine.js-Modul, sonst nichts.

cy.mount() ist dabei kein fest eingebautes Cypress-Kommando, sondern eine Funktion, die pro Framework-Adapter (React, Vue, Angular, Svelte) oder projektspezifisch selbst implementiert wird. Für Alpine.js gibt es keinen offiziellen Adapter, weshalb Hyvä-Projekte einen schlanken eigenen Mount-Befehl schreiben, der HTML-Markup in die Test-Runner-Seite injiziert und anschließend Alpine.initTree() darauf aufruft. Das Ergebnis ist ein Test, der exakt dieselbe Alpine-Reaktivität prüft wie im echten Theme, jedoch ohne Magento-Rendering, PHP-Templating oder Netzwerk-Requests im Testpfad.

2. Architektur: Warum Component Tests ohne Server auskommen

Der entscheidende Architekturunterschied liegt darin, was den Browser überhaupt zum Rendern bringt. Bei E2E-Tests navigiert Cypress zu einer echten URL, der Magento-Webserver liefert vollständiges HTML, PHP-Templates werden serverseitig gerendert und der Browser lädt sämtliche Assets der Seite. Bei Component Tests gibt es keinen Magento-Request: Ein lokaler devServer bündelt ausschließlich die zu testende Komponente und bettet sie in eine minimale, von Cypress bereitgestellte Test-HTML-Seite ein. Es existiert kein PHP-Prozess, keine Datenbankverbindung und kein Session-State, der vor dem Test aufgebaut werden müsste.

Diese Isolation hat einen direkten Effekt auf die Fehlerquellen, die ein Test aufdecken kann. Ein Component Test kann niemals einen kaputten Magento-Layout-Handle oder eine fehlerhafte GraphQL-Query aufdecken, weil diese Schichten schlicht nicht Teil des Testaufbaus sind. Er deckt dafür präzise auf, ob die Alpine-Logik selbst korrekt reagiert: Ob ein Klick auf den Plus-Button den Zustand erhöht, ob eine Grenze greift, ob eine CSS-Klasse bei einem bestimmten Zustand gesetzt wird. Diese Präzision macht Fehlermeldungen deutlich aussagekräftiger als ein fehlgeschlagener E2E-Schritt irgendwo im Checkout-Flow.

3. Cypress-Konfiguration: devServer und specPattern für Component Tests

cypress.config.js unterscheidet zwischen einem e2e- und einem component-Schlüssel, die vollständig getrennte Konfigurationen erlauben. Der auffälligste Unterschied ist devServer: E2E-Tests brauchen kein Bundling, weil der Browser fertiges HTML vom Webserver bekommt. Component Tests hingegen benötigen zwingend einen Bundler, der die Komponente inklusive ihrer Abhängigkeiten für den Browser kompiliert. Cypress unterstützt dafür Webpack, Vite und vorgefertigte Framework-Definitionen; für ein Hyvä-Projekt ohne eigenes JS-Framework reicht meist eine schlanke Vite-Konfiguration, die nur für Testzwecke existiert und nicht Teil des Produktions-Builds ist.

Auch specPattern unterscheidet sich bewusst. E2E-Spezifikationen liegen typischerweise gesammelt unter cypress/e2e/, weil sie Nutzerflüsse über mehrere Seiten hinweg beschreiben. Component-Tests dagegen liegen idealerweise direkt neben der getesteten Komponente, zum Beispiel als cart-quantity.cy.js im selben Verzeichnis wie cart-quantity.phtml. Das verkürzt die kognitive Distanz zwischen Implementierung und Test und macht sofort sichtbar, welche Komponenten noch keine Tests besitzen.

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  // E2E configuration - full page navigation against a running Magento instance
  e2e: {
    baseUrl: 'https://mironsoft.test',
    specPattern: 'cypress/e2e/**/*.cy.js',
    supportFile: 'cypress/support/e2e.js',
  },

  // Component testing configuration - no Magento backend required
  component: {
    devServer: {
      framework: 'vite',
      bundler: 'vite',
      viteConfig: require('./vite.config.js'),
    },
    // Specs live next to the component, not collected in one folder
    specPattern: 'src/**/*.cy.js',
    supportFile: 'cypress/support/component.js',
    indexHtmlFile: 'cypress/support/component-index.html',
  },
});

4. Setup für Hyvä-Projekte: Mount-Command und Support-Datei

Damit cy.mount() für eine Alpine-Komponente funktioniert, braucht es eine einmalige Einrichtung in cypress/support/component.js. Dort wird Alpine.js importiert, global auf window gebunden und ein eigener Cypress-Befehl registriert, üblicherweise cy.mountAlpine(). Dieser Befehl injiziert das HTML-Fragment der Komponente in die Test-Seite und ruft danach Alpine.initTree() auf dem eingefügten Knoten auf, damit x-data, x-on und x-model korrekt initialisiert werden, exakt wie beim regulären Seitenaufbau im Theme.

Zusätzlich definiert component-index.html eine minimale HTML-Hülle mit den nötigen Tailwind- und Alpine-Script-Tags, damit Klassen und Interaktionen visuell und funktional identisch zum echten Theme aussehen. Wichtig ist, dass diese Hülle bewusst schlank bleibt: Sie lädt keine Magento-spezifischen Assets, keine RequireJS-Module und keine Session-abhängigen Skripte. Genau das ist der Punkt, der Component Tests von E2E-Tests unterscheidet und sie so viel schneller macht.

5. Praxisbeispiel: Eine Cart-Quantity-Komponente isoliert testen

Ein gutes Beispiel für Component Testing ist die Cart-Quantity-Komponente eines Hyvä-Themes: ein kleines Alpine-Widget mit Plus-/Minus-Buttons, einem Zahlenfeld und einer Lagerbestandsgrenze. Fachlich relevant sind hier ausschließlich Fragen wie: Erhöht der Plus-Button den Wert korrekt? Wird der Button deaktiviert, sobald der Lagerbestand erreicht ist? Kann der Wert nie unter eins fallen? Keine dieser Fragen braucht ein echtes Produkt, einen echten Warenkorb oder eine echte Magento-Session, sie lassen sich vollständig gegen die isolierte Komponente beantworten.

Der Test mountet die Komponente mit definierten Startwerten und prüft das Verhalten über data-testid-Selektoren, die stabil bleiben, selbst wenn sich CSS-Klassen durch ein Tailwind-Update ändern. Weil kein Netzwerk-Request beteiligt ist, läuft ein solcher Test typischerweise in unter einer Sekunde durch, inklusive Rendering, Interaktion und Assertion. Genau diese Geschwindigkeit macht Component Tests zum bevorzugten Werkzeug für Interaktionslogik, während echte Warenkorb-Persistenz weiterhin ein Fall für E2E-Tests bleibt.

<!-- app/design/frontend/Mironsoft/default/Magento_Checkout/templates/cart/cart-quantity.phtml -->
<div
    x-data="cartQuantity({ initial: 1, max: 99, stock: 25 })"
    class="flex items-center border border-gray-300 rounded-lg"
    data-testid="cart-quantity"
>
    <button type="button" @click="decrement()" :disabled="qty <= 1" class="px-3 py-2 disabled:opacity-40" data-testid="qty-decrement">-</button>
    <input type="number" x-model.number="qty" @change="clamp()" class="w-12 text-center border-0" data-testid="qty-input">
    <button type="button" @click="increment()" :disabled="qty >= max" class="px-3 py-2 disabled:opacity-40" data-testid="qty-increment">+</button>
</div>

<script>
// Alpine component factory, registered via Alpine.data() in the theme's app.js
function cartQuantity({ initial, max, stock }) {
    return {
        qty: initial,
        max: Math.min(max, stock),
        increment() {
            if (this.qty < this.max) this.qty++;
        },
        decrement() {
            if (this.qty > 1) this.qty--;
        },
        clamp() {
            this.qty = Math.min(Math.max(this.qty, 1), this.max);
        },
    };
}
</script>

// src/components/cart-quantity.cy.js
describe('CartQuantity component', () => {
  it('increments the quantity up to the available stock', () => {
    cy.mountAlpine('cart-quantity', { initial: 1, max: 99, stock: 3 });

    cy.get('[data-testid="qty-input"]').should('have.value', '1');
    cy.get('[data-testid="qty-increment"]').click().click();
    cy.get('[data-testid="qty-input"]').should('have.value', '3');

    // Stock limit reached - the increment button must be disabled
    cy.get('[data-testid="qty-increment"]').should('be.disabled');
  });

  it('never lets the quantity drop below one', () => {
    cy.mountAlpine('cart-quantity', { initial: 1, max: 99, stock: 10 });

    cy.get('[data-testid="qty-decrement"]').should('be.disabled');
    cy.get('[data-testid="qty-input"]').should('have.value', '1');
  });
});

6. Geschwindigkeit: Der Feedback-Loop im direkten Vergleich

Der Geschwindigkeitsunterschied zwischen Component- und E2E-Tests ist in der Praxis kein kleiner Faktor, sondern typischerweise eine Größenordnung. Ein E2E-Test gegen eine Hyvä-Checkout-Seite braucht einen laufenden Magento-Container, eine befüllte Datenbank, Full-Page-Cache-Aufwärmung und mehrere Sekunden Ladezeit, bevor der erste Klick überhaupt möglich ist. Ein kompletter E2E-Lauf über zwanzig Szenarien dauert damit schnell zehn Minuten oder mehr. Derselbe Umfang an Interaktionslogik als Component Tests formuliert läuft in der Regel in unter dreißig Sekunden durch, weil weder Server-Rendering noch Netzwerklatenz im Testpfad liegen.

Dieser Unterschied entscheidet direkt über den Feedback-Loop während der Entwicklung. Component Tests lassen sich im Watch-Modus offen halten, während an einer Komponente gearbeitet wird, und liefern bei jeder Speicherung sofort ein Ergebnis, vergleichbar mit einem Unit-Test. E2E-Tests eignen sich dagegen für den Pre-Merge- oder Nightly-Lauf, nicht für den Sekunden-Takt der aktiven Entwicklung. Wer beide Ebenen konsequent trennt, bekommt schnelles Feedback während der Arbeit und trotzdem vollständige Absicherung vor dem Deployment.

7. Die Testing-Pyramide: Unit, Component oder E2E?

Die klassische Testing-Pyramide beschreibt ein Mengenverhältnis: viele schnelle Unit-Tests an der Basis, weniger Integrationstests in der Mitte, wenige langsame E2E-Tests an der Spitze. Cypress Component Testing schiebt sich als eigene Ebene zwischen Unit- und E2E-Tests ein, weil es zwei Eigenschaften kombiniert, die sich bisher ausschlossen: echtes Browser-Rendering wie ein E2E-Test, aber Isolation und Geschwindigkeit fast wie ein Unit-Test. Für reine Funktionslogik ohne DOM-Bezug, etwa eine Preisformatierungs-Funktion oder eine Validierungsregel, bleibt ein klassischer PHPUnit- oder Jest-Unit-Test trotzdem die richtige und günstigste Wahl.

Als Faustregel gilt: Unit-Tests für isolierte Funktionen ohne DOM, Component-Tests für Alpine-Komponenten mit eigenem Zustand, eigenen Interaktionen und sichtbarem Rendering, E2E-Tests für Nutzerflüsse, die mehrere Seiten, echte Magento-APIs und Session-Zustand über Schritte hinweg verbinden, zum Beispiel den kompletten Checkout von der Produktseite bis zur Bestellbestätigung. Ein Dropdown-Menü oder eine Mengenauswahl gehört fast immer in die Component-Ebene, ein vollständiger Bestellprozess fast immer in die E2E-Ebene.

8. CI-Integration: Component Tests in der Pipeline

In der CI-Pipeline zahlt sich die Trennung zwischen Component- und E2E-Tests doppelt aus. Component-Tests benötigen weder einen laufenden Magento-Container noch eine Datenbank noch Testdaten-Fixtures, sie lassen sich als eigener, sehr schneller CI-Job direkt nach npm ci ausführen, oft in unter einer Minute für ein ganzes Set an Komponenten. Das macht sie zum idealen ersten Gate in einer Pull-Request-Pipeline: Schlägt ein Component-Test fehl, bricht die Pipeline ab, bevor der deutlich teurere E2E-Job mit vollem Docker-Stack überhaupt gestartet wird.

package.json trennt beide Testarten in eigene npm-Skripte, damit sie sowohl lokal als auch in CI unabhängig voneinander aufrufbar sind. In GitHub Actions oder GitLab CI lässt sich der E2E-Job dann explizit vom Erfolg des Component-Jobs abhängig machen, sodass unnötige Docker-Startzeiten entfallen, wenn bereits die isolierte Komponentenlogik fehlerhaft ist. Dieses Muster reduziert die durchschnittliche Feedback-Zeit einer Pull Request spürbar, ohne die Absicherungstiefe der E2E-Suite zu verringern.

{
  "name": "mironsoft-hyva-theme",
  "scripts": {
    "test:component": "cypress run --component",
    "test:component:watch": "cypress open --component",
    "test:e2e": "cypress run --e2e",
    "test": "npm run test:component && npm run test:e2e"
  },
  "devDependencies": {
    "cypress": "^13.13.0",
    "vite": "^5.2.0"
  }
}

# .github/workflows/frontend-tests.yml
name: frontend-tests
on: [pull_request]

jobs:
  component-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      # Component tests need no Magento container, no database, no fixtures
      - run: npm run test:component

  e2e-tests:
    runs-on: ubuntu-latest
    needs: component-tests
    steps:
      - uses: actions/checkout@v4
      - name: Start Magento stack
        run: docker compose up -d
      - run: npm run test:e2e

9. Component Testing im direkten Vergleich

Die drei Testebenen unterscheiden sich in Geschwindigkeit, Isolation, Setup-Aufwand und Aussagekraft so deutlich, dass die Wahl der richtigen Ebene direkt über die Wartbarkeit der gesamten Testsuite entscheidet. Die folgende Übersicht fasst zusammen, wann welche Ebene das bessere Werkzeug ist.

In der Praxis ergänzen sich alle drei Ebenen, statt sich gegenseitig zu ersetzen. Eine gesunde Teststrategie für ein Hyvä-Projekt investiert die meiste Zeit in Component-Tests für Interaktionslogik, ergänzt sie um wenige gezielte Unit-Tests für reine Funktionen und sichert die geschäftskritischen Nutzerflüsse zusätzlich mit einer schlanken E2E-Suite ab, statt hunderte E2E-Szenarien zu pflegen, die dieselbe Logik doppelt und langsam prüfen, die ein Component-Test längst in Millisekunden abgedeckt hätte.

10. Zusammenfassung

Component Testing mit Cypress löst ein konkretes Problem: Alpine.js-Komponenten in Hyvä-Themes lassen sich isoliert, im echten Browser und ohne Magento-Backend testen, statt bei jeder kleinen Änderung auf einen kompletten E2E-Lauf zu warten. cy.mount() rendert eine einzelne Komponente mit definierten Startwerten, devServer und specPattern trennen Component- von E2E-Konfiguration sauber, und data-testid-Selektoren machen Tests stabil gegenüber CSS-Änderungen. Das Ergebnis ist ein Feedback-Loop, der sich wie ein Unit-Test anfühlt, aber echtes DOM-Rendering und echte Alpine-Reaktivität prüft.

Die Testing-Pyramide bleibt dabei der richtige Entscheidungsrahmen: Unit-Tests für reine Funktionslogik, Component-Tests für Alpine-Komponenten mit eigenem Zustand und sichtbarem Verhalten, E2E-Tests für vollständige Nutzerflüsse über mehrere Seiten und echte Magento-APIs hinweg. Wer diese drei Ebenen bewusst trennt, statt alles über E2E-Tests abzudecken, reduziert die durchschnittliche Testlaufzeit drastisch und behält trotzdem die Absicherungstiefe, die ein produktiver Magento-Shop braucht.

11. FAQ: Component Testing mit Cypress