UI Demo Video

UI Demo Video

Record a Playwright-driven walkthrough of the running app into a shareable video, emitting a PNG frame per scene. The frames are the point for the model: Read them after recording to visually verify the UI state, and iterate (fix code or scenario, re-record) until the frames show the expected result. The video is the human-shareable artifact (GitHub PR descriptions accept mp4 drag-drop).

When to use

After UI work that a video can verify: a new element, layout change, or flow. Use proportionate visual feedback with existing tooling. Record a video when requested, required by the repo, or useful within the authorized UI task; a small visual check does not require installing a recording toolchain. Not for API-only or non-visual changes, and not as a test suite: scenes demonstrate and verify visually, they do not assert.

Prerequisites

• The app runs locally. Find the project's documented run path: a project run skill, README, package scripts, and use that; do not invent a launch command.
• Playwright is installed in the project (@playwright/test or playwright) with a Chromium browser available. If absent, use an available browser tool for visual checks and report the video prerequisite. Install a new persistent dependency/browser only when that setup is in the authorized scope, using the repository's package manager and documented setup. Do not silently modify package or lockfiles just to record a demo.
• ffmpeg on PATH for mp4 conversion (optional: the webm is always produced).

Workflow

1. App running first. Start the dev server via the documented run path, in the background, and health-check it before anything else. If booting can reseed or migrate a local dev database, back that file up first. Seed the data the scenes need through the app's real surface: a fixture/seed endpoint, the REST/RPC API, a documented CLI seeder, never direct DB writes: seeded state must pass the same validation real usage does.
2. Copy the harness, then write a scenario file next to it. Copy scripts/harness.mjs from this skill's directory into the project's tmp/ folder: the harness must live inside the project so Node resolves the project's own Playwright install: then write tmp/<scenario>.mjs beside it (example below). Scenes should be short and named for what they prove. Use highlight() to draw the eye to the element under test. List every route the scenario visits in prewarm so dev-compile skeletons stay out of frame.
3. Run it: node tmp/<scenario>.mjs. Outputs land in tmp/<name>/: per-scene PNGs, <name>.webm + <name>.mp4, manifest.json. A scenario failure still saves the video and a scene-FAIL.png; those are debugging evidence, not garbage.
4. Feedback loop (mandatory): Read every scene-*.png with the Read tool and check the UI is actually correct: the element present, states right, no hidden runtime errors or half-loaded skeletons. Inspect unfiltered UI/error evidence first; overlay suppression is presentation-only and must not conceal a verification failure. Wrong → fix in scope and re-record. Only a frame-verified recording counts as evidence.
5. Cleanup: delete the demo entities you seeded (through the same real surface you created them with), stop any dev server you started, and confirm the port is closed.
6. Delivery: provide the local recording and frames. Attach them to a PR or tracker only when existing authorization explicitly covers that external write. When authorized, use the host's supported attachment mechanism; do not turn local verification into an implicit publication step.

Scenario example

import { recordUiDemo } from "./harness.mjs";

const BASE = "http://localhost:3000";

await recordUiDemo(
  {
    name: "my-feature-demo",
    baseUrl: BASE,
    prewarm: ["/items", "/items/42"],
  },
  async ({ page, scene, highlight }) => {
    await scene("list shows the new item", async () => {
      await page.goto(`${BASE}/items`, { waitUntil: "networkidle" });
      await page.getByText("Quarterly report").first().click();
    });
    await scene("detail dialog renders the new action", async () => {
      await page.getByRole("button", { name: "Share" }).click();
      await highlight(page.getByRole("dialog").getByRole("link", { name: "Copy link" }));
    });
  },
);

Notes

• The harness leaves overlays visible by default. After inspecting and preserving unfiltered failure evidence, an optional presentation recording may set hideNextDevOverlay: true or explicit hideSelectors. Those frames alone do not establish that no runtime error occurred.
• Realistic demo data reads better than test slugs: name seeded entities like a user would ("Sprint review"), not "TEST-1234 probe".
• Viewport defaults to 1280×720; override via viewport if the surface needs it.
• mp4 conversion needs ffmpeg on PATH; without it the webm is still produced.
• The app under test must be the working tree you changed: the dev server compiles from source, so a stale server proves old code; restart when in doubt.