| 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
/cypress-demo chat input refactoring
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.
