From 41d3efe330a3134e45a1bdf41fbc474ced9752b7 Mon Sep 17 00:00:00 2001 From: Estelle Picq Date: Sun, 1 Nov 2026 08:18:50 +0100 Subject: [PATCH] feat: add Playwright demo videos agent, instructions, prompts, and examples --- agents/demo-videos.agent.md | 30 ++ .../playwright-demo-videos.instructions.md | 58 +++ prompts/demo-videos.prompt.md | 18 + .../playwright-demo-videos-examples/SKILL.md | 33 ++ .../references/examples.md | 397 ++++++++++++++++++ website/docs/guide/apm-distribution.md | 4 + website/docs/guide/catalog-agents.md | 7 + website/docs/guide/catalog-instructions.md | 2 + website/docs/guide/catalog-prompts.md | 6 + website/docs/guide/catalog-skills.md | 6 + website/docs/guide/domain-docs.md | 15 + 11 files changed, 576 insertions(+) create mode 100644 agents/demo-videos.agent.md create mode 100644 instructions/playwright-demo-videos.instructions.md create mode 100644 prompts/demo-videos.prompt.md create mode 100644 skills/playwright-demo-videos-examples/SKILL.md create mode 100644 skills/playwright-demo-videos-examples/references/examples.md diff --git a/agents/demo-videos.agent.md b/agents/demo-videos.agent.md new file mode 100644 index 0000000..7e12b72 --- /dev/null +++ b/agents/demo-videos.agent.md @@ -0,0 +1,30 @@ +--- +name: Demo Videos +description: "Use when you need to record product demo videos of user journeys (Playwright filmed scenarios with fake cursor, encoded to MP4 for a website). Requires the journeys to film and the output folder." +--- + +You are a specialist at filming short, repeatable demo videos of an application's user journeys. + +## Constraints + +- Scope is the **journeys the user names**. If none are named, propose 2–4 from the app's routes and ask before filming. +- Edit only `demos/**`, the `demos` script and gitignore entries of the app, and the encoded files in the output folder. Do not modify production application code. Report UI defects you hit instead of fixing them. +- Filming, reset and encoding rules are owned by the installed `playwright-demo-videos` instruction. When scaffolding files, follow the installed `playwright-demo-videos-examples` skill (read its `references/examples.md`). +- Reuse the e2e login, credentials and navigation helpers. Never commit passwords. +- Never film real or production data: run against the local dev stack. +- Embedding the videos in a website page is a separate step: do it only when asked, following the VitePress docs instruction when the site is VitePress. + +## Approach + +1. Resolve the app folder, the journeys, and the output folder (usually `/docs/public/videos`). Ask for any that is missing; do not guess the output folder. +2. Check prerequisites: dev stack answers on the e2e `baseURL`, Playwright browsers are installed, `ffmpeg` is on the path. +3. Inspect each journey in the running app (accessible roles, labels, dialogs, server calls) with a throwaway script before writing the scenario. +4. Scaffold `demos/` from the skill if absent, then write one scenario per journey with its off-camera reset. +5. Run the narrowest command per scenario (`npx playwright test --config=demos/playwright.config.ts `), then encode with `node demos/to-mp4.mjs `. +6. Review each MP4: duration with `ffprobe`, and a few extracted frames for readability, cursor visibility and the final state. + +## Done When + +- Every agreed journey has a scenario that passes twice in a row against the same database. +- Each journey has an MP4 and a JPG poster in the output folder, and the reviewed frames show the intended outcome. +- No production application source code was modified, and any UI defect met while filming is reported. diff --git a/instructions/playwright-demo-videos.instructions.md b/instructions/playwright-demo-videos.instructions.md new file mode 100644 index 0000000..f1c83bf --- /dev/null +++ b/instructions/playwright-demo-videos.instructions.md @@ -0,0 +1,58 @@ +--- +description: "Playwright demo-video conventions: filmed user journeys under demos/, fake cursor, human-speed gestures, off-camera reset, ffmpeg MP4 + poster for a docs website. Use when recording or editing product demo videos." +applyTo: "**/demos/**/*.ts,**/demos/**/*.mjs" +--- + +# Playwright Demo Videos + +Demo videos are **filmed scenarios, not tests**: they show a user journey slowly, for a product website. When scaffolding or matching full files, follow the installed `playwright-demo-videos-examples` skill (read its `references/examples.md`). + +## Layout + +``` +/demos/ + playwright.config.ts # own config, never the e2e one + support/director.ts # fake cursor, gestures, edit point, save + scenarios/.demo.ts + to-mp4.mjs # WebM -> MP4 + JPG poster + videos/ # raw output, gitignored + .playwright/ # Playwright output, gitignored +``` + +- One scenario per journey, one `test()` per file, named `.demo.ts`. Output name `-` in kebab-case. +- Script: `"demos": "playwright test --config=demos/playwright.config.ts && node demos/to-mp4.mjs "`. +- Gitignore `demos/videos/` and `demos/.playwright/`. Commit only the encoded MP4 + JPG in the website. + +## Config + +- `testMatch: "**/*.demo.ts"`, `workers: 1`, `retries: 0`, `timeout` ≥ 180 s. +- Fixed `viewport` and `video.size` (default 1440×900), `deviceScaleFactor: 1`, `video: { mode: "on" }`. +- `baseURL` from the same env variable and default as the e2e config. Use the running dev stack; start a `webServer` only when the app has no stack. + +## Filming + +- Playwright does not film the mouse: inject the fake cursor with `context.addInitScript` before the first navigation. +- Every on-camera gesture goes through the director (`click`, `hover`, `type`, `pause`). Never call `locator.click()` / `fill()` on camera: they teleport. +- Type at human speed (`pressSequentially`, ~80 ms per key). Pause 600–1500 ms after each visible outcome, 2–3 s on the final frame. +- Call `director.action()` once the first screen is stable: everything before (blank page, app boot, login, setup) is cut. +- Off-camera setup (login, navigation, reset) uses plain Playwright calls and shared e2e helpers. Do not duplicate login or navigation helpers. +- Assert each step with `expect` so a broken journey fails instead of filming an error. + +## Repeatable runs + +- A scenario must be re-runnable on the same database. Reset what it changes **off camera, before `action()`**: put seeded values back, delete objects created by a previous run. +- Avoid on-camera actions with accumulating side effects (duplicates, clones, history spam) unless the reset removes them. +- Workarounds for UI defects (e.g. `dispatchEvent("click")` on a covered button) are allowed off camera only. Report the defect; never film it. +- Mind auth rate limits: one login per scenario. Never loop logins to retry. + +## Encoding + +- `ffmpeg` is required on the host. Encode H.264 `yuv420p`, `-movflags +faststart`, CRF 18–23, no audio, trimmed at the recorded `start`. +- Write `.mp4` and a `.jpg` poster into the output directory given as argument (usually `/docs/public/videos/`). Never default it. +- Check durations (`ffprobe`) and inspect a few extracted frames before handing over. + +## Website embedding + +- `