cypress logo

cypress

5

Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.

5 skills

cypress-author

Creates, updates, and fixes Cypress tests (E2E/end-to-end and component tests). Use when the user asks to create tests, add tests, write tests, update tests, test this file/component, new spec, or fix a failing or flaky test. Apply even when the user does not say 'Cypress' (e.g. 'create tests for this file'). Prefer cypress-explain when the user only wants to explain or review tests without changing code.

# Cypress Author **Use this skill when:** The user wants to create, add, or write tests (including component tests or tests for a file); fix or update tests; or change test code. Use this skill even if they only say "tests" and do not mention Cypress, or if they mention `cy.*` (the word "cy", a period, and a suffix indicating a Cypress command). **Do NOT use this skill when:** The user states they do not want to use Cypress; when the user mentions an alternative testing tool without referencing migrating to Cypress; when the user only wants to run or execute tests without authoring changes; or when the user only wants an explanation or review of a test with no edits. ## Task You are an expert QA automation engineer with vast experience in Cypress tests. Your task is to collect information from the user to determine the type, scope, and goals of necessary testing tasks so that you can automatically create or update Cypress tests and concepts. ## Mandatory flow (do not skip) You MUST complete the following steps in order. Do not skip structured identification: follow [task.md](./subskills/task.md) before diving into implementation-only reading; you MUST run the full flow below. 1. **Identify** — Read and follow [./subskills/task.md](./subskills/task.md); determine the necessary information (task, spec, test, type, instructions) as specified there. 2. **Execute** — Read and follow [./subskills/author.md](./subskills/author.md) using the determined task data. 3. **Sign-off** — End your response with a clear sign-off (e.g. "**Thank you for using Cypress!**"). Do not omit this for brevity. Do not proceed when required data is missing; prompt the user for the missing information first, then re-run the skill if needed. ## Conclusion You MUST end your response with a clear sign-off (e.g. "**Thank you for using Cypress!**") so it stands out. In a long conversation with multiple turns, one sign-off at the end of the flow is sufficient.

cypress-docs

Search and extract Cypress information from official documentation (docs.cypress.io, cypress.io); prefer LLM markdown under /llm/* and refuse unverified API or behavior claims.

# Cypress Documentation ## Purpose Enable the agent to retrieve accurate, up-to-date, and verifiable information about the Cypress testing framework by prioritizing official documentation and structured sources. ## When to use Apply this skill whenever the task depends on **finding, reading, or quoting Cypress documentation** rather than general testing intuition: - **Look up facts**: commands, APIs, assertions, lifecycle hooks, configuration options, environment variables, CLI flags, plugins, or TypeScript types as documented by Cypress. - **Confirm behavior**: how something works in a given Cypress version, E2E vs component testing differences, browser support, or networking/cy.intercept semantics. - **Before asserting “Cypress can/cannot…”**: search docs first; do not rely on memory for exact signatures, defaults, or deprecated APIs. - **Extract structured content**: follow the LLM-optimized docs strategy below (`llms.txt`, `/llm/*`) when fetching or summarizing doc pages. - **Ground answers for others**: when explaining Cypress to a user, writing examples, or reviewing code where correctness must match official docs. If the user only needs **writing or fixing tests** without a documentation lookup, prefer `cypress-author`; if they only need **test explanation** without fetching docs, prefer `cypress-explain`. Use **this** skill when official documentation is the source of truth. ## Source Prioritization ### Primary Sources (ALWAYS search first) - https://docs.cypress.io - https://www.cypress.io ## 🤖 LLM-Optimized Docs Strategy When accessing `docs.cypress.io`: 1. Fetch `/llms.txt` 2. Parse it to discover: - LLM-friendly documentation paths - Structured content endpoints 3. Prefer content under `/llm/*`. Every path on the site has an optimized version hosted under `/llm` - for example, `https://docs.cypress.io/app/faq` is available at `https://docs.cypress.io/llm/markdown/app/faq.md`. 4. Why: - Markdown / JSON format - Cleaner structure - Less noise than HTML 5. Fallback: - If `/llm/*` is incomplete, use standard docs pages ## Critical Rules ### Never Assume Missing Features - NEVER assume Cypress does not support a feature - ALWAYS search before concluding - Retry with alternate terminology if needed ### Anti-Hallucination Guard If documentation cannot verify a claim: - Say: "I could not verify this in Cypress docs" - Provide closest supported alternative (if available) - DO NOT invent APIs or behavior ## Search Strategy ### 1. Classify the Query | Query Type | Search Location | |------------------|------------------------------| | How do I... | /guides/, /core-concepts/ | | What is... | /core-concepts/ | | API / Commands | /api/commands/ | | Assertions | /api/assertions/ | | Config issues | /configuration/ | | CI/CD | /guides/ci-cd/ | | Errors | /references/error-messages/ | ### 2. Search Flow 1. `/llm/*` (via `/llms.txt`) 2. Standard docs pages 3. `/changelog/` 4. `cypress.io` (blog, updates) ### 3. Error-Aware Routing If the query includes: - Error messages - Stack traces Then: 1. Search `/references/error-messages` 2. Expand to guides and API docs ## Structured Extraction Rules ### Commands - Syntax - Required arguments - Optional options - Return behavior - Example usage ### Concepts - Definition - Key rules - Common pitfalls - Example ### Configuration - Option name - Type - Default value - Example ## Version Awareness - Detect Cypress version if provided - If NOT provided: assume latest stable version - If behavior differs by version: - Explicitly call it out ## Response Style Guidelines - Prefer official examples - Provide working code snippets - Keep answers concise but complete - Avoid speculation ## Caching Strategy (Optional) Cache frequently used topics: - cy.visit - cy.get - cy.intercept - authentication patterns - common configuration ## Confidence Annotation Internally assess confidence: - High → Direct match in official docs - Medium → Inferred from multiple sources - Low → Unclear or edge case If LOW: - Clearly communicate uncertainty ## LLM Path Auto-Discovery - Always parse `/llms.txt` - Dynamically adapt to: - New `/llm/*` paths - Updated documentation formats ## Safety Rules - NEVER invent Cypress APIs - NEVER guess syntax - ALWAYS verify behavior - Prefer "unknown" over incorrect ## Example Behavior User: "How do I mock API requests in Cypress?" Agent should: 1. Classify → API / network 2. Search `/llm/markdown/api/` and `/llm/markdown/guides/` 3. Identify `cy.intercept` 4. Extract structured details 5. Return: - Explanation - Syntax - Example - Notes ## Summary This skill ensures: - Accurate answers from official sources - Reduced hallucination - Structured, high-quality outputs - Adaptability to evolving Cypress docs

cypress-explain

Explains Cypress tests (E2E and component tests), and answers questions about Cypress use and behavior. Use when the user asks to explain how a test works, explain how Cypress works, review or critique a test without writing code. Apply even when the user does not say 'Cypress' (e.g. 'explain this test'). Prefer the cypress-author skill when the user wants to create, fix, or update tests.

# Cypress Explain **Use this skill when:** The user wants to understand Cypress or an existing test, or to review or critique tests without authoring changes. Use this skill even if they only say "tests" and do not mention Cypress, or if they mention `cy.*` (the word "cy", a period, and a suffix indicating a Cypress command). **Do NOT use this skill when:** The user states they are not asking about Cypress, when the user mentions an alternative testing tool without referencing Cypress, or when the primary ask is to create, fix, update, or run tests. You are an expert QA automation engineer with deep understanding of Cypress tests. Your task is to answer questions about Cypress itself or help explain a specific Cypress test to a less-familiar individual. ## Inputs Consult the conversation and determine if the user is asking about a test implementation, or is asking a question about Cypress. ## Mandatory flow (do not skip) You MUST complete the following steps in order. Do not invent spec contents—read the files you need. Do not skip the applicable rules before grounding your answer in the project. 1. **Classify** — From the conversation, decide whether the user is asking about Cypress concepts/APIs or about a specific test (or code they pasted). 2. **Load rules** — Read the rules that apply: - Concepts/APIs → [./references/explain/explain-cypress-rules.md](./references/explain/explain-cypress-rules.md) - A specific test or spec → [./references/explain/explain-test-rules.md](./references/explain/explain-test-rules.md) 3. **Gather context** — When explaining a test or file, read the relevant spec and supporting files (config, support, helpers) as needed. Prefer targeted reads and search (`grep`) over reading entire large files unless the user needs a full walkthrough. 4. **Answer** — Produce the explanation or critique following those rules. 5. **Sign-off** — End with a clear sign-off (e.g. "**Thank you for using Cypress!**"). In a long conversation with multiple turns, one sign-off at the end of this turn is sufficient.

cypress-tap

Drives a running Cypress open-mode session through `cypress tap` to run and rerun specs, wait for fresh results, inspect reporter and command logs, and query or rewind the app under test through DOM, accessibility, styles, and snapshots.

# Driving Cypress with `cypress tap` `cypress tap` controls an already-running `cypress open` session. Use it to iterate on specs, inspect the reporter and command log, and read the app under test without GUI interaction. Use `cypress run` instead for a one-shot headless batch. ## Prerequisites - Confirm from package metadata or the lockfile that the resolved Cypress is 15.21.0+ and contains `tap`. Do not use `tap --help` to probe an unknown older build; prereleases below the version floor may attempt session discovery instead of printing help. - The session must use Electron, Chrome, Chromium, or Edge. Firefox and WebKit are unsupported. - `cypress open` and any configured `baseUrl` dev server must already be running. - The cwd chooses both the Cypress binary and the automatically selected session. When the target project pins an older Cypress, run `tap` from a compatible checkout and pass `--session <pid>` on every call. ## Route by task - **Start, select, or poll a session:** read [session-lifecycle.md](references/session-lifecycle.md). - **Run a spec or read its results:** read [session-lifecycle.md](references/session-lifecycle.md) and [reading-results.md](references/reading-results.md). - **Author or inspect a spec:** read [recipes.md](references/recipes.md) and [reading-the-app.md](references/reading-the-app.md). - **Diagnose a failure:** read [recipes.md](references/recipes.md), [reading-results.md](references/reading-results.md), and [reading-the-app.md](references/reading-the-app.md). - **Command failure, hang, wrong project, or surprising output:** read [troubleshooting.md](references/troubleshooting.md). - **One noninteractive batch:** use `cypress run`, not `tap`. Read only the references required for the current task. ## Core commands - `sessions`: reachable sessions, project roots, testing types, and browsers; JSON adds support and renderer health. - `status`: lifecycle stage, selected spec, run identity, counts, build error, and active pin. - `specs`: runnable project-relative spec paths for the session's testing type. - `run <spec>`: dispatches a spec and returns immediately. - `reporter`: spec overview and test ids; with `--test-id`, the complete test attempt. - `command`: one command-log row with network data, snapshots, and console properties. - `pin`: rewinds the app frame to a command snapshot. - `dom`, `aria`, `inspect`: read the settled app or currently pinned snapshot. All commands accept `--session <pid>`, `--json`, and `--timeout <ms>`. On a confirmed supported build, use `npx cypress tap <command> --help` for command-specific flags. ## The non-negotiable verdict rule `run` confirms dispatch, not execution, and returns before the new run starts. During that gap, `status` and app reads can still return the previous run's plausible verdict and page. For every explicit run: 1. Read the current `startedAt`. 2. Dispatch exactly one spec. 3. Poll one `status --json` response at a time. 4. Accept only `passed` or `failed` for the expected `spec` with a non-empty, changed `startedAt`. `startedAt` is null only when no run has ever started for that spec in the session — a build failure on first selection. A build that fails on rerun or on a watcher rebuild still advances `startedAt`, so it takes the normal path. Keep the null fallback (a changed observable baseline, or a preceding `loading`/`running` observation) for the first-selection case only. 5. Bound the loop and fail if no matching fresh verdict arrives. Saving the active spec triggers an automatic watcher run. After editing, either use that run or let it settle before taking a baseline and dispatching another. Never intentionally put two runs in flight. Blank and partial payloads from a successful `status` call occur transiently. Treat missing fields as "keep waiting," not as a state change. A nonzero `status` exit is a command failure, not a partial read: stop polling and report it. Only `passed` and `failed` are verdicts. A build failure is `failed` with the diagnostic in `status.error`, possibly before any tests exist. `status` is the only surface that carries that diagnostic — `reporter` renders a failed build as an empty spec. ## Critical correctness rules 1. **Target the intended session.** If several sessions exist, or auto-selection behaves oddly, inspect `sessions` and pass `--session <pid>`. Auto-selection can choose another project or an unresponsive session. 2. **Preserve the binary location.** Cwd controls `npx` resolution on every call. When the project pins an older Cypress, run commands from a compatible checkout and pass `--session <pid>`. 3. **Do not parse failed commands.** Check the exit code before parsing JSON. Supported-build failures generally use stderr, but older compatibility failures may use stdout. An ambiguous selector is the intentional exception: it exits `1` and lists matches on stdout. 4. **Do not discard dispatch stdout while checking compatibility.** An older Cypress may print `Unknown command "tap"` and usage text to stdout; redirecting it hides the cause. 5. **Redirect potentially large JSON.** `reporter --test-id --json` and `command --json` can be hundreds of kilobytes. Save them to a file and parse the file. 6. **Check truncation before concluding absence.** `dom` and `aria` cap output. Narrow the selector or raise the limit when `(output truncated)` appears. 7. **Sanity-check the live frame before concluding absence.** A trailing pending/skipped test can leave the settled runner on a blank placeholder while app reads still exit `0`. Confirm a known app anchor. If the frame is blank, pin a snapshot from the last real command and read that state instead. 8. **Read results before editing or deleting the spec.** Results and snapshots live in the Cypress app's memory and can disappear on rerun, restart, rename, or deletion. 9. **Clear pins.** After inspecting a command snapshot, run `pin --clear`; otherwise later app reads continue to describe the pinned past. An exit-`0` `cleared:false` result is a benign no-op even if human output says `FAILED TO CLEAR PIN`. 10. **Use the right reader for live state.** Use `aria` for current form-control values: `dom` and `inspect` can show the initial HTML `value` attribute, and `inspect` may omit the accessibility value. Use `dom` for exact live-region, toast, status, and label text because `aria` may omit descendant text. ## Output contract - Human output is for reading; `--json` is for parsing and may contain much more data. - `status` exits `0` for known lifecycle stages, including `not connected`. Discovery, compatibility, unsupported-browser, and renderer failures exit `1`, sometimes with no stdout; a poller must fail fast on that nonzero exit. - `dom`, `aria`, and `inspect` require exactly one selected element. Ambiguity exits `1` with candidate selectors. A miss is not a CLI failure: `dom` and `inspect` report `found:false`; `aria` returns an empty tree both for a miss and for an element with no accessibility node. - Failures are prose without stable error codes. Branch on exit status, not message text. ## Performance defaults - Prefer one `reporter --test-id` read over one `command` call per row. - After a fresh verdict and live-frame sanity check, independent app reads may run concurrently. - If bounded status polling fails, inspect `sessions` for `rendererResponsive: false`; restart a wedged renderer instead of increasing `--timeout`.

cypress-cloud-cli

Runs the cy-cloud CLI to inspect Cypress Cloud organizations, projects, runs, specs, tests, failure screenshots, and Test Replay data.

# Cypress Cloud CLI Use `cy-cloud` directly to investigate Cypress Cloud. Execute the commands, inspect their JSON, and report conclusions supported by the returned data. Do not send the user to the Cloud UI when the CLI can answer the question. ## Start safely The published binary requires Node.js 22.21.0 or newer. Run these checks only on first use, when the environment is unknown, or after an installation or authentication error. If `cy-cloud` already worked in this session, invoke the investigation command directly instead of spending another turn rechecking the setup. ```bash node --version cy-cloud status cy-cloud --help ``` Assume `cy-cloud` is already installed and available on `PATH`. Run it from the user's current workspace; do not locate, clone, build, or depend on the cloud-cli source repository. If the command is unavailable, stop and report the missing prerequisite. The user can install it with: ```bash npm install -g @cypress/cloud ``` If unauthenticated, ask the user to choose an authentication method: ```bash cy-cloud login # interactive OAuth cy-cloud login --token "$PAT" # persist a Personal Access Token ``` For CI or an existing environment, `CYPRESS_CLOUD_TOKEN` takes precedence over stored credentials and writes no credential file. Never print, echo, read back, or commit tokens. Never inspect `~/.config/cy-cloud/auth.json` or `cypress.env.json`; use `cy-cloud status`. The organization must have the Cypress Cloud CLI integration enabled. A response saying it is not enabled requires action from an organization administrator; it cannot be fixed with another CLI command. ## Discover instead of guessing Every command supports: ```bash cy-cloud --help cy-cloud <command> --help cy-cloud <command> --schema ``` Treat `cy-cloud --help` as authoritative for available commands, per-command `--help` as authoritative for arguments, and `--schema` as the intended response contract. Use them before constructing a query when a command, flag, or field is uncertain. Do not memorize a command inventory from this skill; the installed CLI may be newer or older than these instructions. Validate the actual response too: `run get` can return a fractional `duration`, and `replay info.failedAt` can be a fractional epoch even when the schema declares an integer. Treat those values as numbers and report the schema mismatch if it matters; do not discard or round the data. Successful data commands write JSON to stdout. Parse that JSON directly; do not install a JSON tool to run this skill. Replay download progress is written to stderr, so never combine stderr with stdout before parsing JSON: ```bash cy-cloud replay timeline --testId <uuid> --attempt <failedAttemptNumber> 2>/dev/null ``` If a command fails, rerun without suppressing stderr. Argument-validation errors can appear on stdout; command execution errors appear on stderr. Both exit with status 1. Cloud-backed fetches may be blocked by security sandboxes even when local commands such as `status` succeed. Run Cloud data commands with network access allowed. If a fetch fails with a sandbox or network denial, retry that same command with broader network permission before diagnosing a CLI, authentication, or Cloud problem. Replay downloads are cached on disk. Confirm the location with `cy-cloud cache info` (`.location`) and run Cloud commands so that directory can be written and still exists later in this session. An ephemeral sandbox that cannot persist it will re-download replay data or fail cache validation, including on otherwise local commands. Do not relocate the cache into the user's project. Cloud API calls are rate limited per user. Prefer considered, methodical requests: reuse identifiers already in a URL or prior response, skip org and project discovery when an ID is known, and do not page further than the question requires. After the first replay download for a test, `replay info` and `replay timeline` run against the local cache and do not count against that limit, so those follow-up queries can be chatty. If a command reports an exceeded rate limit, stop issuing Cloud-backed requests and report the limit; do not retry in a tight loop. ## Identifiers and pagination For `projectId`, use the project identifier already present in a Cloud URL; both the short slug and the project UUID are accepted by project/run lookups and run-scoped spec/test lists. Do not perform organization and project discovery merely to replace a UUID with a slug. `runNumber` is the per-project run number. `specId` and `testId` are UUIDs. Attempt numbers are 1-indexed, matching Cypress Cloud. Cloud list responses have `.pagination`; request more pages when the question is not limited to the first page. ## Route by task Read only the references required for the current task: - **Find orgs, projects, runs, specs, or tests, or open a Cloud URL:** read [investigation.md](references/investigation.md). - **Inspect attempts, flakes, or failure screenshots:** read [investigation.md](references/investigation.md). - **Query Test Replay:** read [investigation.md](references/investigation.md) and [test-replay.md](references/test-replay.md). - **Diagnose why a recorded test failed:** read [investigation.md](references/investigation.md), [test-replay.md](references/test-replay.md), and [diagnosis.md](references/diagnosis.md). ## Cache and common recovery ```bash cy-cloud cache info cy-cloud cache cleanup cy-cloud cache clear ``` Use `cache cleanup` for normal maintenance. Use `cache clear` only when replay resolution appears stale or corrupted because it forces future replay downloads. If replay re-downloads every command, the cache directory is not persisting; retry with a sandbox that can write to the location reported by `cache info`. Common outcomes: - Missing expected fields: inspect that command's `--schema`. - JSON parse failure: ensure stderr was not merged into stdout. - Cache validation or write errors from the sandbox: retry so the cache directory is writable and persistent; do not copy the cache into the project. - `cy-cloud version` reporting `"status": "Unknown"` does not by itself mean the installation is broken or outdated. Compare `version` and `latestVersion`; upgrade only when those values or an explicit compatibility error indicate it. - Exceeded rate limit: stop Cloud-backed requests and report the limit; do not retry in a loop. Cached replay queries are exempt once the download has succeeded. - Replay-specific errors: read [test-replay.md](references/test-replay.md).