Was ist cypress tap?

cypress tap ist eine Erweiterung der Cypress CLI, mit der ein KI Agent eine laufende cypress open Session direkt aus dem Terminal steuert. Der Agent startet Specs, liest Fehler und Command Log so, wie du sie in der Cypress App siehst, und prüft DOM und Accessibility Tree der getesteten Anwendung.

Bisher bekam ein Agent nach einem Testlauf nur grün oder rot zurück. Alles, was einen Fehler reparierbar macht, steckte in der Cypress App: Command Log, Fehlermeldung mit Code Frame, der DOM zum Zeitpunkt des Fehlers. cypress tap holt genau diesen Kontext ins Terminal. Der Agent schreibt einen Test, prüft ihn gegen die echte App und korrigiert ihn im selben Loop.

Cypress hat cypress tap am 18. August 2026 mit Version 15.21.0 als Beta veröffentlicht. Die CLI ist kostenlos und ohne Nutzungslimit, braucht kein Cypress Cloud Konto und läuft gegen deine lokale App. Passend dazu gibt es den Skill cypress-tap im Cypress AI Toolkit.

Ein Agent, der Tests schreibt, ohne sie gegen die echte App zu prüfen, rät. cypress tap beendet das Raten, aber nur, wenn das Setup drumherum stimmt: Regeln in der AGENTS.md, saubere data-cy Selektoren, geschützte Testdateien und ein Review vor dem Merge. Bei uns läuft Cypress mit Cypress Cloud in Production, KI Agenten arbeiten in Claude Code und OpenCode. Roland Golla ist Cypress Ambassador und hat Tests von Hand geschrieben, debuggt und repariert, lange bevor Agenten dazukamen. Genau dieses Wissen geben wir den Agenten über Regeln mit.

Im Cypress Workshop mit Roland Golla lernt dein Team Cypress von Grund auf, inklusive Agenten Workflow. In den KI Workshops für Entwicklerteams richten wir cypress tap und die Cypress Skills direkt im Terminal mit ein. Teams, die Agenten schon täglich nutzen, begleiten wir in der Vibe Coding Beratung mit den NCA Agentic AI Coding Guardrails. Wie die Fehlersuche in der Pipeline läuft, zeigt unsere Seite zu Cypress Test Replay.

cypress tap hängt sich an eine Session, die schon läuft. Es startet keinen eigenen headless Lauf. Das bestimmt, was geht und was nicht.

• Cypress 15.21.0 oder neuer. Ältere Versionen lassen sich nicht steuern. Passen CLI und Session nicht zusammen, bricht die CLI mit einem Versionshinweis ab.
• Nur cypress open. Headless Läufe mit cypress run findet die CLI nicht. Für CI bleibt alles wie gehabt.
• Nur Chromium Browser. Chrome, Chromium, Edge und Electron funktionieren, Firefox und WebKit nicht.
• Nur der letzte Lauf. Command Details und DOM Snapshots hält Cypress nur für die jüngsten Tests vor, gesteuert über numTestsKeptInMemory.
• Erst lesen, wenn der Lauf fertig ist. dom, aria, inspect und pin melden RUN_IN_PROGRESS, solange eine Spec läuft.

Ein Punkt wird gern übersehen: Agent und Mensch teilen sich denselben App Frame. Wer im Cypress Fenster klickt, während der Agent arbeitet, ändert, was der nächste Befehl liest. Die Regel bei uns ist einfach: Eine Session, die ein Agent steuert, schaut man an, man fasst sie nicht an.

cypress tap bringt zehn Unterbefehle mit. Jeder gibt standardmäßig lesbaren Text aus und mit --json ein stabiles JSON Ergebnis. Für Agenten und Skripte ist JSON der Vertrag. Jeder Befehl endet mit Exit Code 0 bei Erfolg und 1 bei Fehlern. Mehrere Sessions unterscheidest du über die Prozess ID.

Eine eigene Installation braucht cypress tap nicht. Die Befehle stecken in Cypress selbst. Du aktualisierst Cypress und startest die App im Open Mode mit einem Chromium Browser.

In einem zweiten Terminal im selben Projektordner arbeitet jetzt der Agent. Die CLI findet die laufende Session selbst. Sind mehrere offen, nimmt sie die, deren Projekt zum aktuellen Ordner passt.

Damit der Agent die Befehle kennt, installierst du den Skill aus dem Cypress AI Toolkit. Wir committen Skills immer projektbezogen, damit das ganze Team dieselbe Version nutzt.

Praktisch für Agenten: npx cypress tap --help funktioniert auch ohne laufende Session. Ist eine Session aktiv, kommt die Hilfe aus deren eigenem Schema. So liest der Agent immer die Befehle der Version, die er gleich steuert.

Ein typischer Fall: Der Agent schreibt einen Checkout Test und rät den Selektor .submit-btn. Der Test wird rot. Ohne cypress tap müsstest du jetzt HTML in den Chat kopieren. Mit cypress tap schaut der Agent selbst nach.

Schritt 1: Spec starten und auf ein Ergebnis warten. run kehrt sofort zurück. Das Ergebnis liefert erst status.

Schritt 2: Fehler lesen. reporter zeigt die Übersicht mit Test IDs wie r5. Mit der ID bekommt der Agent Command Log, Fehler und Code Frame des Tests.

Schritt 3: Die Seite zum Fehlerzeitpunkt ansehen. pin setzt den Snapshot eines Commands, danach lesen dom, aria und inspect genau diesen Zustand. Zum Schluss wird der Pin wieder gelöst.

Der Agent sieht jetzt das echte Markup, korrigiert den Selektor auf data-cy und startet die Spec neu. Oft zeigt der Loop auch das Gegenteil: Der Test ist richtig und die App hat einen Bug. Auch das ist ein wertvolles Ergebnis, solange der Agent den Test dann nicht passend biegt.

Weil run sofort zurückkehrt, fragt der Agent status so lange ab, bis ein Ergebnis da ist. Hier passieren die meisten Fehler. Die Cypress Doku nennt vier Fallen, die gehören in jede Agenten Anleitung:

• Nur passed und failed sind Ergebnisse. loading, running und alle anderen Phasen heißen: weiter warten.
• startedAt vergleichen. Ein alter Lauf bleibt lesbar, bis der neue startet. Ein passed mit dem alten Zeitstempel gehört zum vorherigen Lauf.
• loading kann ewig dauern. Eine Spec, die nicht kompiliert, bleibt in loading hängen. Der Poller braucht ein eigenes Timeout.
• passed heißt nicht, dass etwas lief. Eine leere Spec oder nur übersprungene Tests melden ebenfalls passed. Erst results.passed größer null bestätigt einen echten Lauf.

Gerade der letzte Punkt ist bei Agenten kritisch. Ein Agent, der ein it.skip setzt und dann passed meldet, hat nichts bewiesen. Das ESLint Plugin für Cypress mit eslint-plugin-mocha fängt vergessene .only und .skip schon vor dem Lauf ab.

Der Skill erklärt dem Agenten die Befehle. Wann er sie nutzt und was er nicht darf, regelst du in der AGENTS.md, bei Claude Code in der CLAUDE.md. So sieht ein kompakter Abschnitt aus, angelehnt an die Vorlage aus der Cypress Doku und ergänzt um unsere Guardrails:

Die Timeout Zahl ist ein Beispiel. Wähle sie nach der Build Zeit deines Projekts. Wichtig ist nur, dass es überhaupt ein Timeout gibt.

Der Befehl aria liefert den Accessibility Tree so, wie ihn die Browser DevTools zeigen: Rolle, Name und Zustand jedes relevanten Elements. Für einen Agenten ist das oft der günstigste Weg, eine Seite zu verstehen. Der Tree ist viel kleiner als der DOM und zeigt sofort, was ein Screenreader sieht.

Steht bei einem Button nur die Rolle und kein Name, fehlt der Accessible Name. Der Agent ergänzt das Label, startet die Spec neu und prüft den Tree erneut. Für Regeln rund um Darstellung wie Farbkontrast nutzt er inspect, das die berechneten Werte für color und background-color ausgibt.

Spannend für Refactorings: Den ARIA Tree vor und nach einem Umbau als JSON speichern und vergleichen. So sieht das Team sofort, ob ein Element seinen Namen verloren hat. Welche Tools wir sonst für Accessibility Tests einsetzen, steht bei den Accessibility Testing Tools.

cypress tap arbeitet lokal. Was in der Pipeline kaputt ging, weiß Cypress Cloud. Zusammen ergibt das einen geschlossenen Kreislauf:

• Triage in der Cloud. Über Cypress Cloud MCP oder die Cloud CLI cy-cloud holt der Agent die fehlgeschlagenen Tests des letzten Laufs samt Fehler und Test Replay Daten.
• Ursache finden. Fehlermeldung, Replay Timeline und Quellcode zeigen, ob Test oder App schuld sind.
• Lokal verifizieren. Die Cloud CLI liefert den specFilepath. Genau diesen Pfad nimmt cypress tap run entgegen.
• Iterieren. run, status, reporter, bis die Spec lokal grün ist. Erst dann wird gepusht.

Der Mensch bleibt im Loop: Er startet cypress open, reviewt die Änderung und gibt den Merge frei. Mehr zum Umgang mit wackeligen Tests steht bei Flaky Tests in Cypress, zur Abgrenzung von automatischen Reparaturen bei Self Healing Tests.

cypress tap löst ein echtes Problem: Agenten konnten ihre eigene Arbeit nicht prüfen. Es löst nicht das zweite Problem, dass Agenten gern den kürzesten Weg zu grün suchen. Deshalb gilt bei uns in jedem Projekt zuerst: Testdateien und Custom Commands sind geschützt. Der Agent darf neue Specs anlegen und Selektoren korrigieren. Eine Assertion abschwächen, damit der Test grün wird, darf er nicht. Wie wir das absichern, beschreiben die Quality Gates für KI Code.

Zweite Regel: Der Agent arbeitet nur gegen eine lokale Umgebung mit Fake Daten. dom und command können Formularwerte, Tokens und Response Bodies zeigen, und alles, was im Terminal landet, sieht auch das Modell. Die Cypress Doku empfiehlt dafür cy.env für sensible Werte. Wir ergänzen Testdaten aus dem Seed statt echter Kundendaten. Gut zu wissen: Cypress erfasst Telemetrie zur Nutzung der CLI, also Befehlsname, Flags und Fehlerstatus. Wie man das abschaltet, steht im Abschnitt Security der offiziellen Doku.

Weiterlesen: Cypress Grep für Burn Tests nach einer Reparatur, Custom Commands als Bausteine, die der Agent nutzen soll, cy.prompt als weiterer KI Weg in Cypress, UI Coverage für Lücken in der Suite, unser eigenes NCA TESTIFY Cypress Plugin und das NCA Cypress Glossar mit allen Einträgen.

Die wichtigsten Antworten zu Voraussetzungen, Befehlen, Polling, Sicherheit und dem Einsatz mit KI Agenten.