{ "doc": { "id": "app/tooling/cypress-tap", "title": "Drive Cypress with AI agents using cypress tap", "description": "Let Cursor, Claude Code, or any AI agent run your Cypress tests from the terminal, read the failures, and verify fixes against a live Cypress session.", "section": "app", "source_path": "/llm/markdown/app/tooling/cypress-tap.md", "version": "5d7ce60278101ddbd4f6aa3fdeef1e6044552997", "updated_at": "2026-08-18T21:52:34.297Z", "headings": [ { "id": "app/tooling/cypress-tap#cypress-tap-live-cypress-app-context-in-your-terminal", "text": "cypress tap: live Cypress app context in your terminal", "level": 1 }, { "id": "app/tooling/cypress-tap#how-it-works", "text": "How it works", "level": 2 }, { "id": "app/tooling/cypress-tap#requirements", "text": "Requirements", "level": 2 }, { "id": "app/tooling/cypress-tap#available-commands", "text": "Available commands", "level": 2 }, { "id": "app/tooling/cypress-tap#cypress-tap-sessions", "text": "cypress tap sessions", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-status", "text": "cypress tap status", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-specs", "text": "cypress tap specs", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-run", "text": "cypress tap run", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-reporter", "text": "cypress tap reporter", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-command", "text": "cypress tap command", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-pin", "text": "cypress tap pin", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-dom", "text": "cypress tap dom", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-aria", "text": "cypress tap aria", "level": 3 }, { "id": "app/tooling/cypress-tap#cypress-tap-inspect", "text": "cypress tap inspect", "level": 3 }, { "id": "app/tooling/cypress-tap#how-to-use-the-commands", "text": "How to use the commands", "level": 2 }, { "id": "app/tooling/cypress-tap#getting-started", "text": "Getting Started", "level": 3 }, { "id": "app/tooling/cypress-tap#polling-for-a-verdict", "text": "Polling for a verdict", "level": 3 }, { "id": "app/tooling/cypress-tap#debug-a-failing-test", "text": "Debug a failing test", "level": 3 }, { "id": "app/tooling/cypress-tap#read-the-app-at-the-moment-it-broke", "text": "Read the app at the moment it broke", "level": 3 }, { "id": "app/tooling/cypress-tap#use-cypress-tap-with-ai-agents", "text": "Use cypress tap with AI agents", "level": 2 }, { "id": "app/tooling/cypress-tap#let-your-agent-discover-the-commands", "text": "Let your agent discover the commands", "level": 3 }, { "id": "app/tooling/cypress-tap#know-which-json-fields-to-rely-on", "text": "Know which JSON fields to rely on", "level": 3 }, { "id": "app/tooling/cypress-tap#add-cypress-tap-to-your-agents-instructions", "text": "Add cypress tap to your agent's instructions", "level": 3 }, { "id": "app/tooling/cypress-tap#example-prompts", "text": "Example prompts", "level": 3 }, { "id": "app/tooling/cypress-tap#fix-a-failing-test", "text": "Fix a failing test", "level": 4 }, { "id": "app/tooling/cypress-tap#reproduce-a-flaky-test", "text": "Reproduce a flaky test", "level": 4 }, { "id": "app/tooling/cypress-tap#verify-a-test-you-just-wrote", "text": "Verify a test you just wrote", "level": 4 }, { "id": "app/tooling/cypress-tap#explore-an-unfamiliar-page", "text": "Explore an unfamiliar page", "level": 4 }, { "id": "app/tooling/cypress-tap#check-a-refactor-changed-nothing", "text": "Check a refactor changed nothing", "level": 4 }, { "id": "app/tooling/cypress-tap#verify-a-cloud-failure-locally", "text": "Verify a Cloud failure locally", "level": 2 }, { "id": "app/tooling/cypress-tap#with-cloud-mcp", "text": "With Cloud MCP", "level": 3 }, { "id": "app/tooling/cypress-tap#fix-a-ci-failure-end-to-end", "text": "Fix a CI failure end to end", "level": 4 }, { "id": "app/tooling/cypress-tap#with-the-cloud-cli", "text": "With the Cloud CLI", "level": 3 }, { "id": "app/tooling/cypress-tap#reproduce-a-ci-failure-locally", "text": "Reproduce a CI failure locally", "level": 4 }, { "id": "app/tooling/cypress-tap#fix-an-accessibility-violation", "text": "Fix an accessibility violation", "level": 2 }, { "id": "app/tooling/cypress-tap#verify-an-accessibility-fix", "text": "Verify an accessibility fix", "level": 3 }, { "id": "app/tooling/cypress-tap#faqs", "text": "FAQs", "level": 2 }, { "id": "app/tooling/cypress-tap#when-to-use-it", "text": "When to use it?", "level": 3 }, { "id": "app/tooling/cypress-tap#troubleshooting", "text": "Troubleshooting", "level": 3 }, { "id": "app/tooling/cypress-tap#pricing-usage-limits", "text": "Pricing & Usage Limits", "level": 3 }, { "id": "app/tooling/cypress-tap#security-and-privacy", "text": "Security and privacy", "level": 3 }, { "id": "app/tooling/cypress-tap#cli-limitations", "text": "CLI Limitations", "level": 3 }, { "id": "app/tooling/cypress-tap#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "cypress tap: live Cypress app context in your terminal" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Your AI agent can run, watch, and fix Cypress tests as it codes." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "An AI agent can run a Cypress spec and get back pass or fail. What it can't get is everything that makes a failure fixable: the Command Log, the error and code frame, the DOM as it was when the command ran. That detail lives in the Cypress app, where the agent can't reach it." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap` is an extension of the cypress CLI that lets you or an agent interact with an open-mode Cypress session and read its context from the terminal. With it, an agent can run a spec and poll its status, then read the failing test's Command Log and error as the Cypress app shows them. It can also inspect the DOM of the application under test at the moment a command ran." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This allows an agent can verify its own work as it codes, catching and fixing failures in the same loop that created them." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Any agent that can run shell commands can use it, including Cursor, Claude Code, GitHub Copilot, Windsurf, and Codex CLI." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap` is in " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/release-stages.md#Beta", "children": [ { "type": "text", "value": "beta" } ] }, { "type": "text", "value": ". It is enabled by default and no longer expected to change in major ways, but its commands and output can still change in any release while we gather feedback." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "How it works" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Start Cypress in open mode (`cypress open`) in your project, select your test time and a chromium browser, then run `cypress tap` commands from the same project directory in another terminal." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The CLI finds the running Cypress session on its own. If more than one is running, it prefers the one whose project matches your current directory. Use `--instance ` to target a specific session." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Every command prints a human-readable output by default and a JSON result when passed `--json`. Agents and scripts should prefer `--json`." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Requirements" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Only works with `cypress open` sessions, not headless `cypres run` sessions." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Only supports Chromium-based browsers (Chrome, Chromium, Edge, Electron)." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Requires Cypress v15.21.0+" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "If the `cypress tap` CLI and the session it attaches to are on incompatible versions, the CLI stops and reports the version mismatch." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Available commands" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Below is the list of the commands `cypress tap` exposes:" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "What it does" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-sessions", "children": [ { "type": "text", "value": "`sessions`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Lists the running Cypress sessions the CLI can reach." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-status", "children": [ { "type": "text", "value": "`status`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Reports where a session is in its run lifecycle." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-specs", "children": [ { "type": "text", "value": "`specs`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Lists the specs the session can run." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-run", "children": [ { "type": "text", "value": "`run`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Runs (or reruns) a spec by its project-relative path." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-reporter", "children": [ { "type": "text", "value": "`reporter`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Renders the spec report or a specific tests report. The spec report includes what tests ran and their status. A test's reporter view includes routes, hooks, Command Log, and failure details." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-command", "children": [ { "type": "text", "value": "`command`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Prints the details of a specific Command Log entry, including it's time travel snapshots and the captured console properties." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-pin", "children": [ { "type": "text", "value": "`pin`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Renders a past command's DOM snapshot as the live app under test so the `dom`, `aria`, and `inspect` tap commands can inspect it." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-dom", "children": [ { "type": "text", "value": "`dom`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Retrieves the app under test's HTML markup." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-aria", "children": [ { "type": "text", "value": "`aria`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Retrieves the accessibility (ARIA) tree of the app under test." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "#cypress-tap-inspect", "children": [ { "type": "text", "value": "`inspect`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Retrieves the specified element's tag, attributes, computed styles, and box model." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Each subcommands exit with `0` on success and `1` on any failure and accepts these options:" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--session`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Use to target a specific running Cypress instance by its process id (pid)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--json`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Prints the raw JSON result instead of the human-readable rendering" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--help, -h`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Outputs usage information" } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap sessions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Lists the running Cypress sessions the CLI can reach. Pass a listed pid to `--session` to target that session with another `tap` command." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap session" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "SESSIONS (2) PID PROJECT TYPE BROWSER 111 /projects/app e2e Chrome 222 /projects/other component —" }, { "type": "paragraph", "children": [ { "type": "text", "value": "`--json` returns the same rows as an array, with `browserAttached` as a boolean and `browserName` as `null` where the text shows `—`:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "[ { \"pid\": 111, \"projectRoot\": \"/projects/app\", \"testingType\": \"e2e\", \"browserAttached\": true, \"browserName\": \"Chrome\" }, { \"pid\": 222, \"projectRoot\": \"/projects/other\", \"testingType\": \"component\", \"browserAttached\": false, \"browserName\": null }]" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap status" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Reports where a running Cypress session is in its lifecycle. It is built for polling, see " }, { "type": "link", "title": null, "url": "#polling", "children": [ { "type": "text", "value": "Polling for a verdict" } ] }, { "type": "text", "value": "." } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Stage" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Meaning" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`not connected`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "No running Cypress session could be found" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`browser not selected`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A session is running, but it has no browser open" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`spec not selected`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A browser is open, but no spec has been chosen" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`loading`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A spec is selected and waiting on its own build. A spec that fails to build stays here, so a poller needs its own timeout" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`running`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The selected spec is executing" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`passed`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The run finished and no test failed" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`failed`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The run finished with at least one failing test" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap status" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "PID PROJECT TYPE BROWSER4242 /projects/app e2e Chrome● cypress/e2e/login.cy.ts running✓ 1 ✖ 1 ○ 2" }, { "type": "paragraph", "children": [ { "type": "text", "value": "With `--json`, the output includes `startedAt` from `loading` onwards: the run's start time, or `null` while the spec is still building. Always check `startedAt` before trusting a verdict. A rerun leaves the previous run's `passed` or `failed` result readable until the new run starts, so a verdict carrying the earlier `startedAt` describes the previous run, not yours." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "With --json, the output carries startedAt from loading onwards (the run's start time, or null while the spec is still building), and adds totalTests and per-outcome results counts from running onwards. A pinned object rides along whenever a pin is active." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"status\": \"loading\", \"pid\": 4242, \"projectRoot\": \"/projects/app\", \"testingType\": \"e2e\", \"browserAttached\": true, \"browserName\": \"Chrome\", \"totalSpecs\": 3, \"spec\": \"cypress/e2e/login.cy.ts\", \"startedAt\": \"2026-07-29T10:15:00.000Z\", \"totalTests\": 5, \"results\": { \"passed\": 1, \"failed\": 1, \"pending\": 2, \"skipped\": 1 }" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap specs" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Lists the specs the current session can run, ordered by last-modified from available git history. The list reflects the session's current testing type; to see the other type's specs, open a session with that type selected." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap specs" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "SPECS (2) cypress/e2e/a.cy.ts 2 hours ago cypress/e2e/longer-name.cy.ts" }, { "type": "paragraph", "children": [ { "type": "text", "value": "`--json` returns the spec paths as an array." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap run" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Runs (or reruns) a spec by its project-relative path, as listed by the " }, { "type": "link", "title": null, "url": "#cypress-tap-specs", "children": [ { "type": "text", "value": "`specs`" } ] }, { "type": "text", "value": ". If no browser is open, Cypress launches one. The command requests the spec starts and returns immediately, returning does not mean the run started. Poll the " }, { "type": "link", "title": null, "url": "#cypress-tap-status", "children": [ { "type": "text", "value": "`status`" } ] }, { "type": "text", "value": " command for progress; see " }, { "type": "link", "title": null, "url": "#polling", "children": [ { "type": "text", "value": "Polling for a verdict" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap run cypress/e2e/login.cy.ts" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "▶ cypress/e2e/login.cy.ts testing type e2e browser Chrome" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap reporter" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Shows test results on the command line the way the Cypress app shows them in its reporter panel." } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--test-id, -t`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Test id, as listed by the spec overview this command prints" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The spec-level overview" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--attempt, -a`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "1-based attempt, where attempt 1 is the first run" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The latest attempt" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Without `--testId`, it prints the spec-level report which includes the run's test stats and every suite's tests, with the test ids the other commands accept." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap reporter" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress/e2e/login.cy.ts✓ 2 ✖ 1 ○ 1 00:17 r1 ✓ redirects an anonymous visitor 20msLogin r2 ✓ shows the sign-in form 10ms r4 ○ remembers the last userLogin > Invalid credentials r3 ✖ shows an error banner 30ms (2 retries) ✖ attempt 1 4.5s ✖ attempt 2 4.4s ✖ attempt 3 30ms" }, { "type": "paragraph", "children": [ { "type": "text", "value": "With `--test-id `, it renders that test's last attempts details including its network routes, the hooks that ran, the complete Command Log, and, when the test failed, the error with its code frame. Add `--attempt` to view an earlier retry." } ] }, { "type": "code", "lang": null, "meta": null, "value": "✓ Login > shows the sign-in formBEFORE EACH · h1 1 visit https://example.cypress.io/todoTEST BODY · r2 1 get .login 2 -assert to be visible 3 get .password 4 -assert to be visible" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap command" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Details one Command Log entry of a test: its reporter row, the DOM snapshots pinnable on it, and its console properties: what the browser's developer tools console shows after clicking the command in the Cypress app." } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--test-id, -t`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Test id, as listed by the " }, { "type": "link", "title": null, "url": "#cypress-tap-reporter", "children": [ { "type": "text", "value": "`reporter`" } ] }, { "type": "text", "value": " command" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Required" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--command-id, -c`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Command id, as listed by the `reporter` command: a row number, an e-prefixed event id, or hook-qualified like `h1:3`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Required" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--attempt, -a`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "1-based attempt, where attempt 1 is the first run" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The latest attempt" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--depth, -d`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "How many levels of nested console properties to expand before summarizing the rest: a number or `all`. A section over 8 rows folds at any depth unless this is passed" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`3`" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap command --test r2 --command 3" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "TEST BODY · r2✓ 3 -contains Submit passedSNAPSHOTS (2) # NAME TIME 1 - 14:03:22.481CONSOLE PROPS Content Submit Applied To Elements 0" }, { "type": "paragraph", "children": [ { "type": "text", "value": "When console properties are deeply nested, cypress tap expands them to --depth levels (default 3) and summarizes the rest. A footer lists what it summarized and how to open it:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap command --test r4 --command e1 --depth 0" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "CONSOLE PROPS Resource Type xhr Method POST URL https://jsonplaceholder.cypress.io/comments Matched `cy.intercept()` {4 keys} Alias postComment1 section collapsed — open one with --path 'Matched `cy.intercept()`', or all of it with --depth all" }, { "type": "paragraph", "children": [ { "type": "text", "value": "A value long enough to bury the rest of the payload, such as a response body, is shown as a note of its length instead of being printed to the terminal. You can pass `--json` to get every console property if needed." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap pin" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pins a command's DOM snapshot into the live app-under-test frame, just like you would see if you manually clicked the command in the Cypress app. This time travel behavior allows the " }, { "type": "link", "title": null, "url": "#cypress-tap-dom", "children": [ { "type": "text", "value": "`dom`" } ] }, { "type": "text", "value": ", " }, { "type": "link", "title": null, "url": "#cypress-tap-aria", "children": [ { "type": "text", "value": "`aria`" } ] }, { "type": "text", "value": ", and " }, { "type": "link", "title": null, "url": "#cypress-tap-inspect", "children": [ { "type": "text", "value": "`inspect`" } ] }, { "type": "text", "value": " commands read the page as it was when that command ran." } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--test-id, -t`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Test id, as listed by the " }, { "type": "link", "title": null, "url": "#cypress-tap-reporter", "children": [ { "type": "text", "value": "`reporter`" } ] }, { "type": "text", "value": " command" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Required" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--command-id, -c`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Command id, as listed by the `reporter` command: a row number, an e-prefixed event id, or hook-qualified like `h1:3`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Required" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--at`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Which snapshot to pin, either a name like `before`/`after`, or a 1-based index" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The last snapshot, the command's final state" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--attempt, -a`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "1-based attempt, where attempt 1 is the first run" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The latest attempt" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--clear`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Release the current pin and restore the app to its pre-pin state" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Off" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap pin --test-id r3 --command-id h2:1 --at after" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "⚲ PINNED - (2/2) afterBEFORE EACH · h2 1 task db:seed" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pins can't be created while a spec is running, and snapshots are kept only for the most recent tests (see " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Global", "children": [ { "type": "text", "value": "`numTestsKeptInMemory`" } ] }, { "type": "text", "value": "). A rerun releases the pin, since the snapshot it named belongs to the previous run." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Don't touch the Cypress window while cypress tap is driving it. A pin is the same state the app changes when you click a command in the Command Log, so the two step on each other:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Release the pin in the app and you release the one cypress tap set." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Pin a command in the app and you change what dom, aria, and inspect read, while status still reports no pin." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap dom" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Reads the app under test's DOM as HTML: the whole page, or the `outerHTML` of each element matching a CSS selector (each match includes its full subtree). Output is capped so a heavy page never ships megabytes at once. The spec must be complete to use this command." } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--selector, -e`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "CSS selector matching exactly one element" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`body`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--max-chars, -m`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Cap on returned HTML characters" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`30000`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--at`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "When a selector matches multiple elements, the 0-based index of the match to read" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`0`" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap dom --selector .todo-list" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "" }, { "type": "paragraph", "children": [ { "type": "text", "value": "When the selector provided is not unique, use `--at` to help identify the right element." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap dom --selector li" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap dom --selector li" }, { "type": "paragraph", "children": [ { "type": "text", "value": "⚠ selector 'li' matched 25 elements but must be unique provide --at with an index to select an element from the list or update the selector. index selector" }, { "type": "break" }, { "type": "text", "value": "0 '.dropdown' 1 '.dropdown-menu > :nth-child(1)' 2 '.dropdown-menu > :nth-child(2)' 3 '.dropdown-menu > :nth-child(3)' 4 '.dropdown-menu > :nth-child(4)' 5 '.dropdown-menu > :nth-child(5)' 6 '.dropdown-menu > :nth-child(6)' 7 '.dropdown-menu > :nth-child(7)' 8 '.dropdown-menu > :nth-child(8)' 9 '.dropdown-menu > :nth-child(9)'" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "showing the first 10 of 25 matches — --at takes any index up to 24." } ] }, { "type": "code", "lang": null, "meta": null, "value": "```shell title=\"Command\"cypress tap dom --selector li --at 2" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap aria" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Reads the accessibility (ARIA) tree of the app-under-test frame, or the subtree rooted at a CSS selector. Structural and text-only roles are dropped, leaving the compact role/name/state tree browser developer tools show." } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--selector, -e`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "CSS selector matching exactly one element" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`body`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--max-nodes, -m`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Cap on the number of accessibility nodes returned" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`200`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--at`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "When a selector matches multiple elements, the 0-based index of the match to read" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`0`" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap aria" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "ARIA (4) http://localhost:3000 RootWebArea Login heading Sign in textbox Username = ada [disabled] button Submit" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cypress tap inspect" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Inspects the first element matching the selector: its tag, attributes, box model, accessibility node, and computed styles. A full computed style runs to roughly 350 properties, so `inspect` reports a fixed subset of two dozen that answer why an element looks or behaves the way it does, covering layout, visibility, text, and the box." } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--selector, -e`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "CSS selector matching exactly one element" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`body`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`--at`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "When a selector matches multiple elements, the 0-based index of the match to read" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`0`" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress tap inspect --selector \"[data-testid=username]\"" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "input [data-testid=username] http://localhost:3000ATTRIBUTES (2) data-testid username name usernameACCESSIBILITY role textbox name Username states disabledBOX x 8 y 40 width 200 height 30STYLES (2) display block color rgb(0, 0, 0)" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "How to use the commands" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Getting Started" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Start Cypress in your project and pick a testing type and browser:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress open --e2e --browser=chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "List the specs the session can run:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap specs" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "SPECS (2) cypress/e2e/checkout.cy.ts 2 hours ago cypress/e2e/login.cy.ts" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pick a spec to run. The command returns as soon as the run is requested, and does not wait for the result:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap run cypress/e2e/checkout.cy.ts" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "▶ cypress/e2e/checkout.cy.ts testing type e2e browser Chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Poll `status` until it reports a verdict. `status` always exits 0 for a determinable stage, so a poller branches on the output, not the exit code. See " }, { "type": "link", "title": null, "url": "#polling", "children": [ { "type": "text", "value": "Polling for a verdict" } ] }, { "type": "text", "value": " for the traps (stale verdicts, empty specs that still pass, and builds that never leave loading)." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap status" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "PID PROJECT TYPE BROWSER4242 /projects/app e2e Chrome✖ cypress/e2e/checkout.cy.ts failed✓ 3 ✖ 1 ○ --" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The run failed, so read the spec's reporter overview to find the failing test:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap reporter" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress/e2e/checkout.cy.ts✓ 3 ✖ 1 ○ -- 00:12Checkout r2 ✓ shows the cart summary 1.4s r3 ✓ removes an item from the cart 610ms r4 ✓ shows the shipping estimate 540ms r5 ✖ applies a discount code 4.5s" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The ids on the left (`r5`) are how every other command addresses a test. From here, debugging is three commands away." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Polling for a verdict" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap run` returns immediately, so you learn a run's outcome by polling its status. Four things to know before you trust what it reports:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Only passed and failed are verdicts. Every other stage (loading, running, and so on) means the run isn't done. Keep polling." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Verify that `startedAt` changed. A finished run stays readable until the next one starts, so a passed/failed still carrying the previous run's `startedAt` describes the previous run. Record `startedAt` before you rerun, and wait for a verdict whose startedAt differs. 0 loading can be terminal. A spec that fails to build sits in loading and never leaves. Give your poller its own timeout." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "passed doesn't mean tests ran. A spec with no tests, or whose tests were all skipped or pending, finishes passed with results.passed at 0. Read the results counts alongside the stage when it matters that something actually ran." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Debug a failing test" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Ask for the failing test's full reporter view: the same routes, hooks, Command Log, and error you'd read in the Cypress app." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap reporter --test r5" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "✖ Checkout > applies a discount code failedTEST BODY · r5 1 get .discount-code 2 -type SAVE10 3 get .apply-discount 4 -click 5 get .cart-total 6 -assert expected
to have text $45.00 ✖✖ AssertionError Timed out retrying after 4000ms: expected '' to have text '$45.00', but the text was '$50.00' cypress/e2e/checkout.cy.ts:42:7 40 | cy.get(\".discount-code\").type(\"SAVE10\"); 41 | cy.get(\".apply-discount\").click(); > 42 | cy.get(\".cart-total\").should(\"have.text\", \"$45.00\"); | ^ 43 | });" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The error and code frame often answer the question on their own. Here the discount code was entered and applied, but the cart total never changed, so the bug is in the application rather than the test." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When the error and code frame aren't enough on their own, drill into a single Command Log entry. The `command` command shows one row's hook section, its pinnable DOM snapshots, and its console properties: what you'd see in the browser's developer tools console after clicking the command in the app." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Look at the `.apply-discount` click, command 3 in test r5:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap command --test-id r5 --command-id 3" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "TEST BODY · r5✓ 3 -click .apply-discount passedSNAPSHOTS (2) # NAME TIME 1 before 14:03:22.481 2 after 14:03:22.613" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Read the app at the moment it broke" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The commands above tell you what Cypress did. To see what the page looked like at the moment a given command ran, pin that command's DOM snapshot into the live app-under-test frame:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap pin --test-id r5 --command-id 3 --at after" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "⚲ PINNED - (2/2) afterTEST BODY · r5 3 click .apply-discount" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pinning from the terminal does the same thing to the Cypress window as clicking that command in the app would: the app-under-test frame switches to the historical snapshot, and stays there until the pin is released." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Leave the Cypress window alone while `cypress tap` is driving it. Both share one app-under-test frame, so clicking in the app changes what the next command reads. Releasing a pin in the app releases your agent's, and pinning one yourself is invisible to `status`, which only reports pins `cypress tap` created." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "While a pin is active, `dom`, `aria`, and `inspect` read the pinned snapshot instead of the app's final state. Inspect the element the failing assertion cared about:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap inspect --selector \".cart-total\"" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "input .cart-total http://localhost:3000ATTRIBUTES (2) class cart-totalACCESSIBILITY role text name $50.00BOX x 220 y 480 width 120 height 28STYLES (2) display block color rgb(0, 0, 0)" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The snapshot confirms it: at the moment the assertion ran, `.cart-total` read `$50.00`, the pre-discount price. The click was logged as passed and the element is present and visible, so nothing swallowed the interaction, the discount simply never applied to the total. That points squarely at the discount logic in the app, not the test." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`dom` returns HTML (whole page or per selector, capped at 30,000 characters by default), and `aria` returns the compact role/name/state tree that browser developer tools show (capped at 200 nodes by default), which is often the cheapest way for an agent to understand a page. Release the pin when you're done:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap pin --clear" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "⚲ PIN CLEARED" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fix the code, `cypress tap run` the spec again, and poll `status` until it reports `passed`." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Use cypress tap with AI agents" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap` is built to be driven by AI agents:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`--json` is the contract. Every command's JSON output is stable and parseable, and the formatted terminal output is built from it." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Output is bounded. DOM, accessibility, and console-property payloads are capped by default so a heavy page never floods an agent's context, with explicit options to raise the caps when needed." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The CLI describes itself. `--help` lists the commands the attached Cypress session advertises, so an agent can discover the surface at runtime instead of relying on documentation that may not match the version you have installed." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Let your agent discover the commands" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap --help` prints every command with its arguments and options. `cypress tap --help` prints one command in detail." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap --helpnpx cypress tap pin --help" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Help is always available. It does not need a browser open, and with no Cypress session running at all the CLI falls back to the command schema it ships with, so an agent can read the surface before asking you to start anything. When a session is attached, help is generated from that session's own schema and leads with the session it resolved, so what your agent reads matches the Cypress it is about to drive." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Know which JSON fields to rely on" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fields arrive as the run progresses, so an agent should treat most of them as conditional rather than assuming a fixed shape. In `status`:" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Field" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Present when" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`status`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Always" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`pid`, `projectRoot`, `testingType`, `browserAttached`, `browserName`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A Cypress session was found, so every stage except `not connected`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`totalSpecs`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A browser is attached, so `spec not selected` onwards" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`spec`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A spec is selected, so `loading` onwards" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`startedAt`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`loading` onwards, and `null` until the run starts" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`totalTests`, `results`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The run has started, so `running` onwards" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`pinned`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A pin created by `cypress tap` is active" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Elsewhere, `sessions` always reports all five of its fields, using `null` for an absent testing type or browser. `specs` always reports `relativePath` and adds `lastModified` only where git history is available. `command` always reports `snapshots`, as an empty array when the row has none to pin, and omits `consoleProps` entirely when the driver has none to give." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A field that does not apply is absent rather than `null`, except where a `null` is meaningful in itself, as with `startedAt` while a spec is still building." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Add cypress tap to your agent's instructions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To make your agent use it, add instructions to the file your agent reads: `AGENTS.md` for Cursor, Codex CLI, and most others, `CLAUDE.md` for Claude Code, or `.github/copilot-instructions.md` for GitHub Copilot." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "AGENTS.md" } ] }, { "type": "code", "lang": null, "meta": null, "value": "## Verify changes with CypressVerify your work against the live Cypress session using the `cypress tap` CLI.Prefer `--json` output.1. Check for a session with `npx cypress tap status`. If it reports `not connected`, ask me to start one with `npx cypress open`.2. List runnable specs with `npx cypress tap specs`.3. Run the affected spec: `npx cypress tap run `. It returns immediately. Poll `npx cypress tap status --json` until `status` is `passed` or `failed`, and compare `startedAt` to confirm the verdict belongs to your run, not the previous one. Give the poll a timeout: a spec that fails to compile stays `loading`, so stop and tell me to check the Cypress app rather than polling forever.4. Treat `passed` with a `results.passed` of `0` as nothing having run, not as a success, and tell me which tests were skipped.5. On failure, run `npx cypress tap reporter` for the spec overview, then `npx cypress tap reporter --test ` for the failing test's Command Log and error.6. Drill into one command with `npx cypress tap command --test --command `.7. To see the DOM at a past command, pin it with `npx cypress tap pin `, read it with `dom`, `aria`, or `inspect `, then release it with `npx cypress tap pin --clear`.8. Do not read the app while a run is in progress; wait for a verdict, then rerun the spec after each fix until it passes.9. Before reading the app, check that `status --json` reports the pin you expect. Tell me if it doesn't, rather than reading the page anyway, since it means the Cypress window was touched while you were working." }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Example prompts" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "With that in place, you can hand your agent a failing test and let it work without relaying results back and forth:" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Fix a failing test" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Points your agent at one failing test and lets it run, diagnose, fix, and verify without you relaying results." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The [test name] test in [spec path] is failing. Use cypress tap to run it, read the failure, find the cause, fix it, and rerun it until it passes." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Reproduce a flaky test" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Runs one spec repeatedly through cypress tap, since a single green run never proves a flake is gone." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The [test name] test in [spec path] is flaky. Use cypress tap to run that spec against my open Cypress session at least 10 times, polling cypress tap status --json for a verdict each time and comparing startedAt so you attribute each verdict to your own run. Record how many runs passed and failed. For every failure, capture the command log with cypress tap reporter --test " }, { "type": "html", "value": "" }, { "type": "text", "value": " and compare the failing runs against the passing ones to identify what differs, such as timing, network responses, or leftover state." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Verify a test you just wrote" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Has your agent run the test it wrote and confirm it passes for the right reason, rather than because nothing ran." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You just wrote tests in [spec path]. Use cypress tap to run that spec against my open Cypress session and poll cypress tap status --json until it reports a verdict. Confirm from the results counts that your tests actually ran rather than being skipped, and use cypress tap reporter to show me each test's command log so I can see what it asserted. If anything failed, fix it and rerun." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Explore an unfamiliar page" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Reads the accessibility tree of the app under test, which is a compact way for an agent to learn a page's structure before writing tests against it." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Use cypress tap to run [spec path], which ends on the page I want to test. Once it reports a verdict, read the page with cypress tap aria and summarize its structure: the landmarks, headings, forms, and interactive controls, with the accessible name of each. Then suggest the selectors you would use to write tests against it, and tell me which controls have no accessible name to target." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Check a refactor changed nothing" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Captures the accessibility tree before and after a change, so an agent can tell you exactly what moved." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Before I refactor [component or page], use cypress tap to run [spec path] and save the output of cypress tap aria --json. I will tell you when the refactor is done. Then rerun the same spec, read the tree again, and show me a diff of what changed in roles, names, and states, calling out anything that lost an accessible name." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap` pairs well with " }, { "type": "link", "title": null, "url": "/llm/markdown/app/tooling/ai-skills.md", "children": [ { "type": "text", "value": "Cypress AI Skills" } ] }, { "type": "text", "value": ": the skills teach your agent how to write good Cypress tests, and `cypress tap` tells it what happened when those tests ran." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Verify a Cloud failure locally" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress Cloud tells your agent what broke in CI. `cypress tap` lets it prove the fix against a real browser before pushing. Reach Cloud with either " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-mcp.md", "children": [ { "type": "text", "value": "Cloud MCP" } ] }, { "type": "text", "value": ", if your agent speaks the Model Context Protocol, or the " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-cli.md", "children": [ { "type": "text", "value": "Cloud CLI" } ] }, { "type": "text", "value": ", if it runs shell commands." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "With Cloud MCP" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your agent queries Cypress Cloud through Cloud MCP for the failing or flaky tests in the latest run, and reads each failure's error and stack trace." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your agent changes the test or the application code to address what the failure showed." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You start a session with `cypress open` and pick a testing type and browser, so there is something for `cypress tap` to attach to." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your agent runs the same spec with `cypress tap run `, polls `cypress tap status --json` for a verdict, and reads the failure with `cypress tap reporter --test ` if it is still red." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your agent repeats steps 2 and 4 until the spec passes locally, then you push a change you already know works." } ] } ] } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Fix a CI failure end to end" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Chains Cloud MCP and cypress tap: diagnose from the recorded run, fix, then verify locally before pushing." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using Cypress Cloud MCP, find the failing tests in the latest run on this branch. For each failure, read the error and stack trace to work out the cause, then fix the test or the application code. I have Cypress open locally, so after each fix use cypress tap to run that spec against my session and poll cypress tap status --json until it reports a verdict. Keep going until every spec you touched passes locally, then summarize what you changed and why." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "With the Cloud CLI" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Both tools speak JSON, and the " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-cli.md", "children": [ { "type": "text", "value": "Cloud CLI" } ] }, { "type": "text", "value": " reports each failing test's `specFilepath`, which is the same project-relative path `cypress tap run` takes. Your agent can hand the path straight from one command to the other." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "1. Find the last failed run on your branch." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy-cloud run list --projectId abc123 --branch main --status failed --limit 1" }, { "type": "paragraph", "children": [ { "type": "text", "value": "2. List its failing tests. Each result carries the spec path, the test id, and the error." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy-cloud test list --projectId abc123 --runNumber 4021 --status failed" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"tests\": [ { \"specFilepath\": \"cypress/e2e/checkout.cy.ts\", \"testName\": [\"Checkout\", \"applies a discount code\"], \"testId\": \"7c1e9d20-5a3b-4c8d-9e0f-1a2b3c4d5e6f\", \"status\": \"failed\", \"attempts\": [ { \"attemptNumber\": 1, \"errorName\": \"AssertionError\", \"errorMessage\": \"expected '.cart-total' to have text '$45.00'\" } ] } ]}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "3. Reconstruct the failure from CI. Pull the commands, network calls, and console logs around the failure, which is the context Test Replay shows in the browser." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy-cloud replay timeline --testId 7c1e9d20-5a3b-4c8d-9e0f-1a2b3c4d5e6f \\ --commands --aroundFailure 5 --network --logs" }, { "type": "paragraph", "children": [ { "type": "text", "value": "4. Fix the code, then rerun that spec locally. `cypress tap` needs a live session to attach to, so start one with `cypress open` and pick a testing type and browser first. Then feed the `specFilepath` straight to `cypress tap run`." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress open" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap run cypress/e2e/checkout.cy.ts" }, { "type": "paragraph", "children": [ { "type": "text", "value": "5. Poll for the verdict." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap status" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "PID PROJECT TYPE BROWSER4242 /projects/app e2e Chrome✖ cypress/e2e/checkout.cy.ts failed✓ 4 ✖ 1 ○ --" }, { "type": "paragraph", "children": [ { "type": "text", "value": "6. Read the local failure and compare it to CI. `reporter --test ` gives you the same command log the replay timeline gave you for the CI run, so your agent can see whether the failure it reproduced is the one it set out to fix." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap reporter --test r5" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Repeat steps 4 to 6 until `status` reports `passed`, then push a change you already know works." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Reproduce a CI failure locally" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Chains the Cloud CLI and cypress tap: pull the failure from CI, rerun that spec against your local session, and iterate until it passes." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Use the cy-cloud CLI to find the most recent failed run on " }, { "type": "html", "value": "" }, { "type": "text", "value": " for project " }, { "type": "html", "value": "" }, { "type": "text", "value": " and list its failing tests. For each one, read the error and pull the replay timeline around the failure, then work out the cause and fix the test or the application code. After each fix, run that test's specFilepath with cypress tap run against my local Cypress session, poll cypress tap status --json until it reports a verdict, and read the failure with cypress tap reporter if it is still red. Keep going until every spec you touched passes locally, then summarize what you changed and why." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Fix an accessibility violation" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/accessibility/get-started/introduction.md", "children": [ { "type": "text", "value": "Cypress Accessibility" } ] }, { "type": "text", "value": " reports violations against the pages your tests already visit, and " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-mcp.md", "children": [ { "type": "text", "value": "Cloud MCP" } ] }, { "type": "text", "value": " hands your agent the failing elements. What it can't tell your agent is what the browser actually computes for an element now, which is the thing most accessibility rules turn on." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "1. Get the failing elements. Cloud MCP's `cypress_get_accessibility_rule_failures` returns each failing element's CSS selector, its view, and the failure message. Ask for one rule at a time." } ] }, { "type": "blockquote", "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Show me the `button-name` failures from the latest run on this branch." } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Say it reports `.cart-item__remove` on the `/checkout` view, with the message that the button has no accessible name." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "2. Run a spec that reaches that view. `aria` reads the app under test as the run left it, so run a spec that ends on the page you care about, and wait for a verdict." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap run cypress/e2e/checkout.cy.ts" }, { "type": "paragraph", "children": [ { "type": "text", "value": "3. Read the element's accessibility node. Pass the selector Cloud gave you." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap aria --selector \".cart-item__remove\"" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "ARIA (1) http://localhost:3000/checkout button" }, { "type": "paragraph", "children": [ { "type": "text", "value": "A bare role with no name next to it is the violation, made concrete: the browser resolves no accessible name for this button at all. An icon-only button whose `aria-label` never made it to the DOM looks exactly like this." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "4. Fix it, rerun the spec, and read the node again." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "ARIA (1) http://localhost:3000/checkout button Remove item" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The name now resolves, so the rule passes for that element. Drop the selector to read the whole page's tree instead, which is a cheap way for an agent to check that a fix didn't break the structure around it:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Command" } ] }, { "type": "code", "lang": null, "meta": null, "value": "npx cypress tap aria" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Output" } ] }, { "type": "code", "lang": null, "meta": null, "value": "ARIA (6) http://localhost:3000/checkout RootWebArea Checkout heading Your cart list Cart items listitem Blue hoodie button Remove item button Place order" }, { "type": "paragraph", "children": [ { "type": "text", "value": "For rules that turn on presentation rather than semantics, such as `color-contrast`, use " }, { "type": "link", "title": null, "url": "#cypress-tap-inspect", "children": [ { "type": "text", "value": "`inspect`" } ] }, { "type": "text", "value": " instead: it reports the element's resolved `color` and `background-color` alongside its accessibility node." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Verify an accessibility fix" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pulls failing elements from Cypress Accessibility, then confirms each fix against the accessibility tree the browser actually computes." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using Cypress Cloud MCP, get the " }, { "type": "html", "value": "" }, { "type": "text", "value": " accessibility failures from the latest run on this branch and list the failing elements with their selectors and views. I have Cypress open locally. For each element, run a spec that reaches its view with cypress tap run, wait for cypress tap status to report a verdict, then read the element with cypress tap aria " }, { "type": "html", "value": "" }, { "type": "text", "value": " and tell me what role, name, and states the browser resolves. Where the accessible name is missing or wrong, fix the markup, rerun the spec, and read it again to confirm the name now resolves." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "FAQs" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "When to use it?" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `cypress tap` CLI gives you the ability to interact and inspect a local Cypress session while developing or debugging tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Both the " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-mcp.md", "children": [ { "type": "text", "value": "Cloud MCP" } ] }, { "type": "text", "value": " and the " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-cli.md", "children": [ { "type": "text", "value": "Cloud CLI" } ] }, { "type": "text", "value": " give programmatic access to your Cypress Cloud data." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Together these tools provide the availability for you or an AI agent to fully engage with Cypress and your recorded Cloud data to author, debug and maintain your test suite without leaving your terminal." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Troubleshooting" } ] }, { "type": "list", "ordered": false, "start": null, "spread": true, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`status` reports `not connected`. No Cypress session was found for this directory. Start one with `cypress open`, and remember that headless `cypress run` sessions are never discoverable." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`status` stays `loading` and never reaches a verdict. The selected spec is waiting on its own build. A spec that fails to compile never starts a run, so it stays `loading` indefinitely and the build error appears only in the Cypress app. Give any poll loop a timeout and check the app when it expires." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A verdict looks wrong, or arrives too fast. Compare `startedAt` against the `previousStartedAt` that `run` returned. A rerun leaves the previous run's verdict readable until the new one starts, and both payloads are otherwise identical." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`passed` with nothing having run. `passed` means the run finished with no failures, so an empty spec, or one whose tests were all skipped, reports `passed`. Read the `results` counts to confirm tests actually ran." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Command details or snapshots are missing on an older test. Cypress keeps them only for the most recent tests. See " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Global", "children": [ { "type": "text", "value": "`numTestsKeptInMemory`" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A read returns something unexpected after you clicked in the Cypress app. The app and `cypress tap` share one app-under-test frame. Check `status --json` for the pin you expect before reading the page." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Pricing & Usage Limits" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `cypress tap` CLI is available for use for all Cypress test authors using Cypress version 15.21.0+ at no cost. Additionally, there are no usage limits." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Security and privacy" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The data exposed from the `cypress tap` CLI into your terminal is strictly local session. If using the CLI within a AI agent, be mindful to ensure you are using safe test practices, like using " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/env.md", "children": [ { "type": "text", "value": "`cy.env()`" } ] }, { "type": "text", "value": ", to prevent leaking sensitive information to your agent." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress does capture telemetry specifically around the usage of the CLI to inform usage patterns. The data collected includes the command name, the flags used and whether it errored. To opt-out of this behavior, set `CYPRESS_DISABLE_GUEST_TELEMETRY=0` in your terminal." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "CLI Limitations" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You must be on Cypress v15.21.0+ or higher to use the CLI. You cannot use `cypress tap` to interact with older versions." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap` reads the most recent run of the open session. Command details and DOM snapshots are kept only for the most recent tests (see " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Global", "children": [ { "type": "text", "value": "`numTestsKeptInMemory`" } ] }, { "type": "text", "value": "), so older tests may report that their details are no longer available." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`dom`, `aria`, `inspect`, and `pin` work only on a completed run. While a spec is running they fail with `RUN_IN_PROGRESS` until the run reports a verdict." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Firefox and WebKit are not supported. `cypress tap` only support interacts with Chromium browsers." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`cypress tap` drives the same session you are looking at, and there is no lock between the two. Starting a run from the app, switching spec, or pinning and unpinning commands all change what your agent's next command reads. Treat a session an agent is driving as one you watch rather than touch." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/app/tooling/ai-skills.md", "children": [ { "type": "text", "value": "Cypress AI Skills" } ] }, { "type": "text", "value": ": teach your agent to write and review Cypress tests" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-mcp.md", "children": [ { "type": "text", "value": "Cloud MCP" } ] }, { "type": "text", "value": ": give your agent access to recorded runs in Cypress Cloud" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-cli.md", "children": [ { "type": "text", "value": "Cloud CLI" } ] }, { "type": "text", "value": ": read runs, failures, and Test Replay timelines from Cypress Cloud in the terminal" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/cypress-ai-features.md", "children": [ { "type": "text", "value": "Cypress AI" } ] }, { "type": "text", "value": ": overview of all AI capabilities across the Cypress app and Cypress Cloud" } ] } ] } ] } ] }, "token_estimate": 8803 }