| name | web-dev-loop |
| description | Run browser-assisted frontend work in this repo through the Compose-managed Playwright lane. Use this when the user asks to test or debug the Next.js frontend with browser automation, capture traces/screenshots, choose between fixture-backed vs live-web checks, or drive the frontend loop without adding a separate browser stack. |
| compatibility | opencode |
Web Dev Loop
Use this for browser-assisted frontend work in {{PROJECT_NAME}}.
When to use
- run Playwright smoke tests for
apps/web
- choose between fixture-backed UI checks and live
web service checks
- capture traces, screenshots, videos, and HTML reports under repo-scoped
tmp/
- keep browser work inside
docker-compose.dev.yml rather than adding host-only tooling
When not to use
- do not use this for backend-only tasks
- do not use this for production browser infrastructure decisions
- do not use this as a substitute for deterministic backend evaluation or dataset validation
Default workflow
- Start from an OpenCode session alias when the work is non-trivial.
- Prefer the fixture-backed smoke lane first:
./dev.sh docker-compose-dev run --rm --profile frontend-tools playwright npm run test:e2e
- If the bug only reproduces against the live app stack, start the relevant services and reuse the running
web server:
./dev.sh docker-compose-dev up -d api web./dev.sh docker-compose-dev run --rm --profile frontend-tools -e PLAYWRIGHT_USE_EXISTING_WEB_SERVER=1 -e PLAYWRIGHT_BASE_URL=http://web:3000 -e {{PROJECT_SLUG}}_WEB_USE_FIXTURES=0 playwright npm run test:e2e
- Use headed or UI mode only when a trace is not enough:
./dev.sh docker-compose-dev run --rm --profile frontend-tools playwright npm run test:e2e:headed./dev.sh docker-compose-dev run --rm --service-ports --profile frontend-tools playwright npm run test:e2e:ui
- For manual local viewing, start the noVNC-based browser viewer:
./dev.sh web-view up./dev.sh web-view url./dev.sh web-view down
- Keep artifacts under
tmp/agent-runs/...; the default location is tmp/agent-runs/playwright/.
Notes
- The browser viewer is local-only by default and binds to
127.0.0.1.
- If
BROWSER_VIEW_EXPOSE_CMD is set, the viewer container will run that command with the internal web port appended so you can layer your own later publish/tunnel mechanism on top.
- The
playwright service is the browser tool lane. The web service is still the interactive Next.js dev server.
- When the task is about actual app behavior, name whether you are using fixture mode or the live web stack in the task contract or checkpoint.
Output
- exact command used
- whether the run used fixtures or the live web stack
- artifact location under
tmp/agent-runs/...
- smallest next step: fix, add regression test, or switch to the live stack
