/cypress-demo

name: cypress-demo
description: >
  Create a Cypress-based video demo for a feature branch with cursor, click
  effects, and captions. Use when recording feature demos, creating PR videos,
  showcasing UI changes, or generating visual walkthroughs. Triggers on: "demo",
  "record demo", "create demo video", "cypress demo", "feature walkthrough",
  "PR video", "showcase".

Cypress Demo

Create a polished Cypress demo test that records a human-paced video walkthrough of UI features on the current branch.

Usage

/cypress-demo                          # Auto-detect features from branch diff
/cypress-demo chat input refactoring   # Describe what to demo

User Input

$ARGUMENTS

Behavior

When invoked, create a Cypress test file in `e2e/cypress/e2e/` that records a demo video with:

• **Synthetic cursor** (white dot) that glides smoothly to each interaction target
• **Click ripple** (blue expanding ring) on every click action
• **Caption bar** (compact dark bar at top of viewport) describing each step
• **Human-paced timing** so every action is clearly visible
• **`--no-runner-ui`** flag to exclude the Cypress sidebar from the recording

1. Determine what to demo

• If `$ARGUMENTS` is provided, use it as the demo description
• If empty, run `git diff main..HEAD --stat` to identify changed files and infer features
• Read the changed/new component files to understand what UI to showcase
• Ask the user if clarification is needed

2. Check prerequisites

• Verify `e2e/.env.test` or `e2e/.env` exists with `TEST_TOKEN`
• Check if `ANTHROPIC_API_KEY` is available (needed for Running state)
• Verify the kind cluster is up: `kubectl get pods -n ambient-code`
• Verify the frontend is accessible: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000`

3. Create the demo test file

Create `e2e/cypress/e2e/<feature-name>-demo.cy.ts` using the helpers below.

Required helpers

Each demo file must define the following helpers inline (they are not shared utilities — embed them directly in the test file):

• **Functions**: `caption()`, `clearCaption()`, `initCursor()`, `moveTo()`, `moveToText()`, `clickEffect()`, `cursorClickText()`
• **Timing constants**: `LONG`, `PAUSE`, `SHORT`, `TYPE_DELAY`

See the patterns table below for usage. If a prior demo file already exists in `e2e/cypress/e2e/`, copy the helpers from there; otherwise implement them fresh using the patterns below.

4. Key patterns

| Pattern | Rule | |---------|------| | **Dual layout** | Session page renders desktop + mobile. Always use `.first()` | | **Caption scoping** | Scope `cy.contains` to a tag to avoid matching caption overlay | | **Workspace setup** | Create workspace, poll `/api/projects/:name` until 200 | | **Caption position** | Always `top:0` — bottom obscures chat toolbar | | **Timing** | Aim for ~2 min total. Adjust constants if too fast/slow | | **Video output** | `e2e/cypress/videos/<name>.cy.ts.mp4` at 2560x1440 |

5. Run the demo

cd e2e
npx cypress run --no-runner-ui --spec "cypress/e2e/<name>-demo.cy.ts"

6. Reference implementation

`e2e/cypress/e2e/sessions.cy.ts` is a reference for test structure and Cypress patterns in this repo. Note that sessions.cy.ts is a functional test, not a demo test — it does not contain the cursor/caption/click-ripple helpers listed above. Use it as a guide for selectors, workspace setup, and polling patterns; implement the demo-specific helpers fresh in your new file.