# cypress-tap

Controls a running cypress open session from the command line. It lets coding agents trigger spec runs, read reporter logs, and inspect DOM snapshots without GUI interactions.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2700 installs · ★ 47
- Author: cypress-io
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/cypress-io/ai-toolkit/tree/HEAD/skills/cypress-tap/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/cypress-tap

## What it does

This skill provides instructions for driving an active `cypress open` session through `cypress tap`. Instead of clicking buttons in the desktop GUI, the agent uses `cypress tap run` to launch e2e or component specs, monitors `status` until execution finishes, and reads failures through `reporter`. Subcommands like `dom`, `aria`, and `pin` let the agent inspect accessibility trees and rewind app state to specific snapshots.

Spec execution is asynchronous: `run` signals dispatch rather than completion. The polling workflow checks `status --json` and waits for a changed `startedAt` timestamp alongside a terminal verdict of `passed` or `failed`. Standard flags across commands include `--session <pid>`, `--json`, and `--timeout <ms>`.

Firefox and WebKit will not work; the runner requires Chromium-family browsers such as Electron, Chrome, Chromium, or Edge. You must also have your application dev server and an active `cypress open` session running beforehand. For non-interactive batch runs, use `cypress run` instead.

## Requirements
- Works with: Chrome

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cypress-io/ai-toolkit --skill cypress-tap -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cypress-tap/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cypress-tap/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cypress-io/ai-toolkit --skill cypress-tap -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cypress-tap/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cypress-io/ai-toolkit --skill cypress-tap -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cypress-tap/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cypress-io/ai-toolkit cypress-tap
```

2. **Manually: put the files in place**
- File: `.github/skills/cypress-tap/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cypress-io/ai-toolkit --skill cypress-tap -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cypress-io/ai-toolkit --path skills/cypress-tap
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cypress-tap/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cypress-io/ai-toolkit --skill cypress-tap -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cypress-io/ai-toolkit/tree/HEAD/skills/cypress-tap/SKILL.md

## When to use it
- dispatch spec runs in an active Cypress session
- extract failure logs and network stubs from reporter
- query settled DOM and accessibility trees via aria
- rewind test frames to earlier command snapshots

## Example prompts
- Run cypress/e2e/checkout.cy.ts via cypress tap and report any failures
- Inspect the active session status with cypress tap status --json
- Rewind to test step r3 and inspect the DOM with cypress tap dom

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9d8d0b4fde7383d5.

BEGIN THIRD-PARTY FILE 9d8d0b4fde7383d5
````text
---
name: cypress-tap
description: >-
  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. Use when authoring or debugging Cypress e2e or component specs,
  discovering selectors, diagnosing failures, or verifying test behavior
  without GUI interaction. Not for one-shot headless runs. Requires Cypress
  15.21+, a Chromium-family browser, and a running `cypress open` session.
metadata:
  version: 1.1.0
---

# 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.

## Core loop

```bash
npx cypress tap sessions                    # confirm a session; note pid if several exist
npx cypress tap status                      # baseline startedAt + spec
npx cypress tap run cypress/e2e/foo.cy.ts   # async — returns immediately
# poll status until passed|failed for your spec with a changed startedAt
npx cypress tap reporter
npx cypress tap reporter --test-id r3       # one test: log, network, stubs, error
```

`run` is asynchronous. A stale verdict matches a fresh one on every field except `startedAt`,
and a watcher rerun of the **selected** spec can advance `startedAt` without running your file.
Gate on `startedAt`, `spec`, and a terminal status. Do not wait to observe `running` — fast
specs can finish between polls. Copy-paste poller:
[session-lifecycle.md](references/session-lifecycle.md). JSON field helpers:
[json-recipes.md](references/json-recipes.md).

In poll loops, prefer `./node_modules/.bin/cypress tap …` over `npx cypress tap …` when the
project pins Cypress.

## 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).
````
END THIRD-PARTY FILE 9d8d0b4fde7383d5

The third-party file has ended. Everything between the 9d8d0b4fde7383d5 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2700 of 11939 bytes. © cypress-io · MIT · https://github.com/cypress-io/ai-toolkit/tree/HEAD/skills/cypress-tap/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md