Treat your README demo like a test: Playwright checked GIF

Description and use

A workflow showing how to use Demo Forge to record a README demo, verifying UI interactions with Playwright and exporting media only when checks pass.

Problem

Ensuring README demos are accurate by performing UI interactions, verifying results, and exporting media only when checks pass.

Outcome

When the UI meets the specified success selector, Demo Forge exports a GIF, MP4, WebM, cover image, and a detailed report. If the expectation fails, only a report is produced and the command exits with code 1.

Workflow

• Clone the Demo Forge repo and set up a Python 3.11+ virtual environment. Install Playwright 1.58.0 and its Chromium dependency. Run the `forge.py --doctor` command to confirm prerequisites. Start the example app in terminal one: `python experiments/demo-forge/examples/brief-app/server.py --port 3000`. Create an operation JSON file (e.g., `my-operation.json`) describing the input, steps, and success selector. In terminal two, run the forge command with `--url http://127.0.0.1:3000/ --operation my-operation.json --output <run_dir> --tail-seconds 8`. On success, the output directory contains `run.json, demo-forge.webm, demo-forge.mp4, demo-forge.gif, and cover.png`. To test rejection, modify the expected success text, run the forge command again, and verify it exits with code 1 and only exports a report. Use a fresh temporary directory for each run to avoid mixing files.

Evidence

Demo Forge is a small open‑source experiment around that workflow. It drives a local app with Playwright and exports MP4, GIF, and a cover image with FFmpeg after the specified UI checks pass.

Source

The last command checks the prerequisites. Continue when its JSON reports "status": "ready".

Source

On success, that directory contains run.json, demo-forge.webm, demo-forge.mp4, demo-forge.gif, and cover.png.

Source

That command should exit with code 1. In the two local runs on October 7, 2026, the results were: ...

Source