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.