Cypress Grep ist das offizielle Plugin @cypress/grep, mit dem du Cypress Tests nach Titel oder Tags filterst. Statt der ganzen Suite läuft nur der Teil, den du gerade brauchst, zum Beispiel alle Tests mit dem Tag @smoke.
Das Plugin wird vom Cypress Team im Cypress Monorepo gepflegt und steht unter MIT Lizenz. Es kann Specs ohne passende Tests vorab überspringen, gefilterte Tests ganz ausblenden und einzelne Tests mehrfach hintereinander laufen lassen, um wackelige Tests zu finden.
Wir setzen Grep für drei Dinge ein: eine schnelle Smoke Stufe in der Pipeline, getrennte Läufe für Production und Stage und Burn Tests für neue Specs. Alle drei zeigen wir weiter unten mit Beispielen.
Jede wachsende Suite kommt an den Punkt, an dem ein Tippfehler zwanzig Minuten Pipeline kostet, bis ihn jemand sieht. Dann fangen Teams an, Tests zu überspringen. Mit @cypress/grep drehen wir die Reihenfolge um: Die wichtigsten Tests laufen zuerst, alles andere danach. Roland Golla ist Cypress Ambassador und kennt dieses Problem aus über zwanzig Jahren Testing und Refactoring. Die erste Stufe bilden bei uns die Basistests aus dem eigenen NCA TESTIFY Cypress Plugin, das mit einer Zeile ins CI/CD Setup kommt.
Die Tag Strategie für dein Projekt bauen wir in den Cypress Power Hours oder im Cypress Workshop mit Roland Golla direkt an deinem Code. Die Stufen in der Pipeline richten wir über das CI/CD Pipeline Setup ein, mit getrennten Läufen für Staging, Docker und Preview URLs. Danach verteilt Cypress Parallelisierung die volle Suite auf mehrere Maschinen, und mit Cypress Test Replay siehst du jeden Fehler aus der CI so, wie er passiert ist.
Ein Tag inhouse mit Roland Golla, offizieller Cypress Ambassador und seit über 20 Jahren in Testing und Refactoring zu Hause. Auf unserem YouTube Kanal zeigt er in über 70 Live Coding Tutorials, wie Cypress in echten Projekten läuft. Dazu kommt unser Open Source Plugin NCA TESTIFY: Basistests für jede Website, mit einer Zeile im CI/CD Setup. Im Workshop lernt euer Team Setup, stabile Selektoren, Custom Commands und Tests in der Pipeline.
Aktuelle Versionen von @cypress/grep setzen Cypress 15.10 oder neuer voraus. Zuerst installierst du das Paket als Dev Abhängigkeit.
npm install --save-dev @cypress/grep
Danach registrierst du Grep in der Support Datei. Ohne diesen Schritt filtert nichts.
// cypress/support/e2e.ts
import { register as registerCypressGrep } from '@cypress/grep'
registerCypressGrep()
Der dritte Schritt ist optional, lohnt sich aber ab mittelgroßen Suiten. Das Plugin in der Konfiguration erlaubt es, Specs ohne passende Tests gar nicht erst zu laden.
// cypress.config.ts
import { defineConfig } from 'cypress'
import { plugin as cypressGrepPlugin } from '@cypress/grep/plugin'
export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
cypressGrepPlugin(config)
return config
},
},
})
TypeScript Typen sind seit Version 5 im Paket enthalten. Falls deine IDE die Option tags nicht kennt, trägst du @cypress/grep zusätzlich unter types in der cypress/tsconfig.json ein.
Tags setzt du als Option an it oder describe. Ein Tag am describe gilt für alle Tests darin. Mehrere Tags gibst du als Array an.
describe('Checkout', { tags: '@checkout' }, () => {
it('legt einen Artikel in den Warenkorb', { tags: ['@smoke', '@critical'] }, () => {
cy.visit('/produkte')
cy.get('[data-cy=add-to-cart]').first().click()
cy.get('[data-cy=cart-count]').should('have.text', '1')
})
it('zeigt alle Versandarten', { tags: '@slow' }, () => {
// ...
})
})
Eine Falle, die wir oft in Reviews sehen: tags: '@smoke @fast' als ein String erzeugt einen Tag mit Leerzeichen, nicht zwei. Für mehrere Tags immer ein Array nutzen.
Auf der Kommandozeile filterst du dann mit --expose. Die Syntax für Kombinationen ist kurz:
npx cypress run --expose grepTags="@smoke"
npx cypress run --expose grepTags="@smoke+@critical"
npx cypress run --expose grepTags="@smoke+-@slow"
npx cypress run --expose grep="Warenkorb",grepTags="@smoke"
Viele Anleitungen im Netz zeigen noch --env grepTags. Das funktioniert mit aktuellen Versionen nicht mehr. Cypress hat Cypress.env() mit Version 15.10 als veraltet markiert und für öffentliche Werte durch Cypress.expose() ersetzt. @cypress/grep ist ab Version 6 mitgezogen.
# alt, bis @cypress/grep 5
npx cypress run --env grepTags="@smoke"
# neu, ab @cypress/grep 6
npx cypress run --expose grepTags="@smoke"
Bei einem Update prüfst du drei Stellen: die Scripts in der package.json, die CI Konfiguration und feste Werte in der cypress.config. Dort heißt der Block jetzt expose statt env. Wer von Version 4 kommt, muss außerdem die Imports umstellen, weil register und plugin seit Version 5 benannte Exporte sind.
Genau solche Umstellungen übersehen KI Agenten gern, weil ihr Trainingswissen die alte Syntax kennt. Ein Grund mehr, Agenten mit aktueller Doku zu versorgen, etwa über die offiziellen Cypress AI Skills, und Pipeline Änderungen immer im Review zu prüfen.
Drei Optionen machen Grep in großen Suiten erst richtig schnell und nützlich:
npx cypress run --expose grepTags="@smoke",grepFilterSpecs=true,grepOmitFiltered=true
npx cypress run --expose grep="Warenkorb",burn=10
npx cypress run --expose grepUntagged=true
Zwei Grenzen solltest du kennen. Negative Filter wie -@slow funktionieren nicht zusammen mit grepFilterSpecs. Und gefilterte Tests können in Cypress Cloud trotzdem als pending in der Aufzeichnung erscheinen.
Die letzte Zeile oben ist ein unterschätztes Werkzeug. grepUntagged zeigt alle Tests ohne Tag. Damit prüfst du regelmäßig, ob neue Tests sauber eingeordnet sind, gerade wenn Agenten Tests schreiben.
Unsere Pipelines laufen in zwei Stufen. Zuerst die Smoke Suite mit @smoke, die in wenigen Minuten zeigt, ob Login, Navigation und die wichtigsten Abläufe funktionieren. Erst wenn sie grün ist, startet die volle Suite parallel über Cypress Cloud. Ein kaputter Build fällt so früh auf und blockiert keine teuren CI Minuten.
# .gitlab-ci.yml
cypress:smoke:
stage: e2e-smoke
image: cypress/included:latest
script:
- npm ci
- npx cypress run --expose grepTags="@smoke",grepFilterSpecs=true,grepOmitFiltered=true
cypress:full:
stage: e2e-full
needs: ['cypress:smoke']
parallel: 4
image: cypress/included:latest
script:
- npm ci
- npx cypress run --record --parallel
Praktisch sind außerdem feste Scripts in der package.json. Dann muss sich niemand die Syntax merken, weder Menschen noch Agenten:
{
"scripts": {
"cy:smoke": "cypress run --expose grepTags=@smoke",
"cy:critical": "cypress run --expose grepTags=@critical",
"cy:burn": "cypress run --expose grepTags=@smoke,burn=5"
}
}
Im interaktiven Modus mit cypress open filterst du übrigens direkt in der DevTools Konsole, zum Beispiel mit Cypress.grep(null, '@smoke'). Ein Aufruf ohne Argumente entfernt den Filter wieder.
Nicht jeder Test darf überall laufen. Auf Production soll ein Test nur schauen: Seite laden, Links prüfen, Inhalte lesen. Auf Stage darf er richtig loslegen, Formulare abschicken, Bestellungen anlegen und Daten ändern. Mit Grep trennst du diese Gruppen sauber über Tags.
describe('Startseite', { tags: '@readonly' }, () => {
it('lädt ohne Fehler und zeigt das Impressum', () => {
cy.visit('/')
cy.get('[data-cy=imprint-link]').should('be.visible')
})
})
describe('Kontaktformular', { tags: '@write' }, () => {
before(() => requireWritableEnv())
it('schickt eine Anfrage ab', () => {
cy.visit('/kontakt')
cy.get('[data-cy=contact-mail]').type('test@example.test')
cy.get('[data-cy=contact-submit]').click()
cy.get('[data-cy=contact-success]').should('be.visible')
})
})
In der Pipeline steuert die Ziel URL, welche Gruppe läuft. Gegen Production laufen nur die lesenden Tests, gegen Stage alles.
# Production: nur schauen
CYPRESS_BASE_URL=https://www.example.de npx cypress run --expose grepTags="@readonly",grepFilterSpecs=true,grepOmitFiltered=true
# Stage: alles, auch schreibende Tests
CYPRESS_BASE_URL=https://stage.example.de npx cypress run
Auf einen Tag allein verlassen wir uns nicht. Jeder schreibende Block bekommt eine kleine Schutzfunktion. Zeigt die baseUrl auf eine Live Umgebung, bricht der Block ab, bevor ein Test etwas abschickt. So landet auch bei einem falsch konfigurierten Job oder einem KI Agenten keine Testbestellung im echten Shop.
// cypress/support/guards.ts
const writableHosts = ['localhost', 'stage.example.de', 'review.example.de']
export function requireWritableEnv() {
const host = new URL(Cypress.config('baseUrl') ?? '').hostname
if (!writableHosts.some((allowed) => host.endsWith(allowed))) {
throw new Error(`Schreibender Test gegen ${host} abgebrochen`)
}
}
Die Liste ist bewusst eine Erlaubnisliste. Neue Umgebungen sind damit erst einmal gesperrt, bis jemand sie freigibt. Die passende Regel für die AGENTS.md steht im nächsten Abschnitt.
Ohne Regeln entstehen in wenigen Monaten @smoke, @Smoke, @smoketest und @quick für dasselbe, und der Filter findet nur noch einen Teil der Tests. Wir arbeiten deshalb mit einer kurzen, festen Liste:
Die Liste steht in der README des Testordners und in der AGENTS.md. Ein KI Agent, der einen neuen Test schreibt, vergibt dann passende Tags, statt neue zu erfinden:
## Cypress Tags
- Erlaubte Tags: @smoke, @critical, @readonly, @write, @slow und Bereichs Tags am describe.
- Jeder Test ist entweder @readonly oder @write.
- Jeder @write Block ruft in before() requireWritableEnv() auf.
- Keine neuen Tags ohne Rücksprache.
- Mehrere Tags immer als Array: { tags: ['@smoke', '@critical'] }
- Neue Tests mit npm run cy:burn prüfen, bevor sie in den Merge Request gehen.
Für Cypress mit KI Agenten ist burn besonders wertvoll. Einen generierten Test, der beim vierten Lauf kippt, schicken wir zurück an den Agenten, bevor er im Merge Request landet.
Filter and organize your Cypress tests with grep and tag-based filtering
Cypress Parallelisierung mit Cypress Cloud: Load Balancing, Spec Priorisierung, GitHub Actions und GitLab CI Beispiele. Praxis vom Cypress Ambassador.
Mehr erfahren
Flaky Tests in Cypress finden und beheben: Ursachen, Retries, Flake Detection in Cypress Cloud und Codebeispiele für stabile E2E Tests, von NCA.
Mehr erfahrenWenn wir eine Suite in Stufen teilen, beginnen wir mit einer Frage an das Team: Welche Abläufe würden morgen das meiste Geld oder den meisten Ärger kosten, wenn sie kaputt wären? Die bekommen @smoke. Alles andere wartet auf die volle Suite und läuft trotzdem bei jedem Merge Request.
Die Basistests aus dem NCA TESTIFY Plugin tragen bei uns zwei Tags. @smoke, weil kaputte Links oder ein fehlendes Impressum sofort auffallen müssen. Und @readonly, weil sie nichts verändern. Deshalb laufen sie zusätzlich als Monitoring gegen Production. Fachliche Tests aus dem Team kommen mit @critical dazu, wenn es um Geld oder Daten geht.
Vor Grep steht bei uns das ESLint Plugin für Cypress, und neue Tests mit passenden Tags schreiben Agenten mit dem Cypress AI Toolkit. Weiterlesen im NCA Cypress Glossar: Cypress UI Coverage, Cypress Custom Commands und unser Artikel zu Quality Gates für KI Code.
Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile einer schnellen, sicheren und barrierefreien Webseite. Erfüllen Sie die gesetzlichen Anforderungen und verbessern Sie die Benutzererfahrung Ihrer Webseite. Mit Astro JS können Sie die Ladezeit reduzieren, die Sicherheit maximieren und die SEO-Optimierung verbessern. Kontaktieren Sie uns, um mehr zu erfahren und um Ihre Webseite auf ein neues Level zu heben.
Die wichtigsten Antworten zu Setup, Tags, expose Syntax, CI und Burn Tests mit @cypress/grep.
Cypress Grep ist das offizielle Plugin @cypress/grep vom Cypress Team. Es filtert Tests nach Text im Titel oder nach Tags, die du an it und describe setzt. So läuft nur der Teil der Suite, den du brauchst, etwa alle @smoke Tests. Zusätzlich kann es Specs vorfiltern, gefilterte Tests ausblenden und Tests wiederholen.
Mit npm install --save-dev @cypress/grep. Danach importierst du register aus @cypress/grep in der Support Datei und rufst registerCypressGrep() auf. Optional bindest du plugin aus @cypress/grep/plugin in setupNodeEvents der cypress.config ein. Das brauchst du, wenn Specs ohne passende Tests gar nicht erst geladen werden sollen.
Weil Cypress Cypress.env() mit Version 15.10 als veraltet markiert und für öffentliche Werte durch Cypress.expose() ersetzt hat. Ab @cypress/grep 6 nutzt du deshalb --expose statt --env, also npx cypress run --expose grepTags="@smoke". Prüfe beim Update package.json Scripts, CI Konfiguration und feste Werte in der cypress.config.
Aktuelle Versionen von @cypress/grep setzen Cypress 15.10 oder neuer voraus, weil sie auf Cypress.expose aufbauen. Ältere Projekte bleiben bei einer älteren Grep Version mit --env Syntax. Wir empfehlen, Cypress und Grep zusammen zu aktualisieren und danach die Smoke Suite einmal komplett laufen zu lassen.
Leerzeichen bedeutet ODER, etwa "@smoke @critical". Ein Plus bedeutet UND, etwa "@smoke+@critical". Ein Minus bedeutet NICHT, etwa "@smoke+-@slow". Titel und Tags kannst du kombinieren, dann müssen beide Filter passen. Negative Filter funktionieren allerdings nicht zusammen mit grepFilterSpecs.
Mit zwei Tags und einer Schutzfunktion. Tests, die nur lesen, bekommen @readonly, Tests mit Formularen oder Bestellungen bekommen @write. Gegen Production läuft nur grepTags="@readonly". Zusätzlich prüft jeder @write Block in before() die baseUrl gegen eine Erlaubnisliste und bricht auf Live Umgebungen ab.
Als Array, also { tags: ['@smoke', '@critical'] }. Ein String mit Leerzeichen wie '@smoke @critical' erzeugt einen einzigen Tag mit Leerzeichen und nicht zwei. Das ist ein häufiger Fehler, auch bei KI generierten Tests. Tags am describe Block gelten für alle Tests darin.
Mit grepFilterSpecs=true lädt Cypress nur Spec Dateien, die passende Tests enthalten. Ohne diese Option lädt es jede Spec und markiert gefilterte Tests nur als pending. Bei großen Suiten spart das viel Zeit. Die Option braucht das Plugin in setupNodeEvents und funktioniert nicht mit negativen Filtern.
Mit der Option burn läuft ein gefilterter Test mehrmals hintereinander, etwa burn=10. Kippt er dabei auch nur einmal, ist er flaky, selbst wenn er beim ersten Lauf grün war. Wir prüfen so jeden neuen Test, egal ob ihn ein Mensch oder ein Agent geschrieben hat.
Mit grepUntagged=true laufen nur Tests, die keinen Tag haben. Das ist ein einfacher Check, ob neue Tests sauber eingeordnet wurden. Wir lassen ihn regelmäßig laufen und ergänzen fehlende Tags, damit Smoke und Critical Suiten vollständig bleiben.
Ja. Im interaktiven Modus rufst du in der DevTools Konsole Cypress.grep auf, zum Beispiel Cypress.grep('login') für den Titel oder Cypress.grep(null, '@smoke') für Tags. Ein Aufruf ohne Argumente entfernt den Filter wieder. Das ist praktisch beim Debuggen einzelner Gruppen.
Ja. Typisch ist eine Smoke Stufe mit grepTags="@smoke" und danach die volle Suite parallel über Cypress Cloud. Beachte, dass gefilterte Tests in Cloud Aufzeichnungen als pending erscheinen können. Mit grepOmitFiltered=true und grepFilterSpecs=true bleibt die Aufzeichnung übersichtlicher.
Eine kurze, feste Liste. Bei uns sind das @smoke für Pflichtabläufe, @critical für Geld, Daten und Recht, @readonly und @write für die Frage, ob ein Test Daten ändert, @slow für lange Tests und Bereichs Tags am describe. Die Liste steht in der AGENTS.md, damit Menschen und Agenten dieselben Tags nutzen.
