| name | cc-run-browser-driven-web-app-example |
| description | Example file for the Run app skill showing how to start a web dev server, drive it with chromium-cli, capture screenshots, and document app-specific gotchas |
Example: Browser-driven web app
You have a dev server that serves HTML to a browser. An agent in a
headless container can't open a browser window — so "run the app" means
launching the dev server, driving a headless Chromium against it, and
producing a screenshot that proves the page rendered.
Don't write a browser driver. Use chromium-cli.
Dev server
Find the dev command (package.json scripts.dev, Makefile,
README), start it in the background, and wait for it to actually serve:
npm run dev &
echo $! > /tmp/dev.pid
timeout 30 bash -c 'until curl -sf http://localhost:3000 >/dev/null; do sleep 1; done'
Don't sleep 5 — poll the port. Stop with
kill $(cat /tmp/dev.pid) (or pkill -f 'npm run dev') before
relaunching, or the next run hits EADDRINUSE.
Drive
chromium-cli is a headless-Chromium REPL. Pipe a script to stdin:
chromium-cli --session app <<'EOF'
nav http://localhost:3000
wait-for text=Dashboard
screenshot
click button:has-text("New item")
fill input[name="title"] Smoke test
press Enter
wait-for text=Smoke test
screenshot
console --errors
EOF
Screenshots land in chromium_cli/sessions/app/screenshots/ (latest
symlinked as screenshot.png). That's the whole loop: nav →
wait-for the element you need → act (click / fill / type /
press) → screenshot → console --errors to check nothing threw.
Full command reference: chromium-cli skill, or help at the prompt.
For iterative debugging, run it under tmux and send-keys one command
at a time — same commands, same session.
If chromium-cli isn't available: adapt
electron.md's REPL driver — the structure and commands
transfer, but it's _electron-specific:
import { chromium } instead, launch with
chromium.launch({ args: ['--no-sandbox'] }), acquire the page via
(await app.newContext()).newPage() then goto() your dev URL, and
drop the Electron-only window introspection
(.windows()/.firstWindow()/the windows command).
What to put in the skill
The project-specific bits only. chromium-cli handles the mechanics.
- Dev command + port + stop. The exact start line, any env vars it
needs, and the
kill/pkill to stop it.
- Auth. Whatever gets a logged-in session — a
set-cookie line, a
fill/click login sequence, or a helper script that does the API
dance and emits the cookie.
- One representative interaction. Not the whole app — one path that
proves it's running, ending in a screenshot.
- App-specific gotchas. Only the ones you actually hit.
Gotchas that recur
- React controlled inputs.
eval el.value = '…' doesn't fire
React's onChange. Use fill / type — they go through Playwright's
input pipeline.
- Websockets / long-poll.
wait-idle never settles. wait-for the
element you actually need.
- Slow first paint. Vite/Next compile routes on demand; the first
nav can take 10s+. wait-for handles it; raw sleep doesn't.
screenshot-element <sel> crops to one element — use it when the
diff is in a specific component, not the whole page.- Check
console --errors before declaring success. A page can
render its shell while every data fetch 500s.
