Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.
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.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 docsExplains 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.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`.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).