From agent-flow
Default verification tool for local HTML files. Use visual-check.sh as the FIRST choice whenever you need to verify, test, or check any local HTML page — whether confirming elements render correctly, checking layout, detecting overflow, or asserting uniform widths. Prefer this over raw playwright-cli commands. Also the authoritative reference for playwright-cli setup and gotchas in this project — always load this skill before using playwright-cli directly.
npx claudepluginhub timgranlundmarsden/claude-agent-flowThis skill uses the workspace's default tool permissions.
**This is the authoritative reference for all playwright-cli usage in this project.**
Captures full-page screenshots, navigates authentication flows, runs Lighthouse audits, and tests responsive design using playwright-cli without writing code.
Tests local web applications using Playwright: verifies frontend functionality, debugs UI behavior, captures screenshots, views logs. Mandatory before declaring implementation complete.
Captures screenshots of web pages, UIs, Reveal.js slides, and email templates using Playwright for visual review, layout verification, and iteration.
Share bugs, ideas, or general feedback.
This is the authoritative reference for all playwright-cli usage in this project.
The vendored playwright-cli skill may be replaced by /sync-plugin-skills and
lacks project-specific setup knowledge. Always load this skill (playwright-cli-helpers)
alongside or instead of playwright-cli when doing browser work.
When both playwright-cli and playwright-cli-helpers skills are loaded, always
start with playwright-cli-helpers:
visual-check.sh (this skill).
It handles server setup, sandbox config, mobile+desktop screenshots, and overflow
detection in one command.playwright-cli commands (from the vendored skill) when
you need interactive browser work that visual-check.sh can't do — e.g. clicking
elements, filling forms, navigating between pages, or checking computed styles.playwright-cli, follow the setup guidance in this skill (sandbox,
no file:// URLs, correct binary name) — not just the vendored skill's examples.Local helper scripts that wrap playwright-cli for common visual verification tasks.
Location: .claude/skills/playwright-cli-helpers/scripts/visual-check.sh
Screenshots a local HTML file at mobile (375px), tablet portrait (768px), and desktop (1280px) widths, checks for horizontal overflow, and optionally asserts uniform element widths for a CSS selector.
# Basic check — screenshots + overflow detection
scripts/visual-check.sh path/to/file.html
# With uniform-width assertion on a CSS selector
scripts/visual-check.sh path/to/file.html ".card"
PASS + paths to three screenshots (mobile, tablet, desktop) on successFAIL: horizontal overflow at 375px (mobile) with scroll/client widths on overflowFAIL: non-uniform widths for '.card': [300, 298, 301] on width mismatchUse the --evidence <task-folder> flag to save JPEG screenshots directly.
The folder name should match the backlog task filename (without .md), e.g.
task-50 - Fix-mobile-grey-horizontal-line-on-breadcrumb-nav.
# Saves mobile.jpg + tablet.jpg + desktop.jpg as JPEG (quality 80), stages with git add
.claude/skills/playwright-cli-helpers/scripts/visual-check.sh path/to/file.html --evidence "task-50 - Fix-mobile-grey-horizontal-line-on-breadcrumb-nav"
# With a prefix — produces no-grey-line_mobile.jpg, no-grey-line_tablet.jpg, no-grey-line_desktop.jpg
.claude/skills/playwright-cli-helpers/scripts/visual-check.sh path/to/file.html --evidence "task-50 - Fix-mobile-grey-horizontal-line-on-breadcrumb-nav" no-grey-line
# With selector check too
.claude/skills/playwright-cli-helpers/scripts/visual-check.sh path/to/file.html ".card" --evidence "task-50 - Title"
Naming convention: <prefix>_<viewport>.jpg — the prefix describes the
specific change, the suffix is the viewport. A task touching multiple things should
have evidence for each:
.scratch/evidence/task-42 - Update-nav-and-badges/
new_badge_mobile.jpg
new_badge_tablet.jpg
new_badge_desktop.jpg
moved_link_mobile.jpg
moved_link_tablet.jpg
moved_link_desktop.jpg
The --evidence flag without a prefix produces generic mobile.jpg + tablet.jpg + desktop.jpg.
With a prefix (--evidence <folder> <prefix>), filenames become <prefix>_mobile.jpg, etc.
Use the prefix when a task has multiple evidence captures in the same folder.
For targeted screenshots of specific changes, crop to the relevant element:
playwright-cli run-code "async page => {
const el = await page.$('.badge-container');
await el.screenshot({ path: '.scratch/evidence/<task-slug>/new_badge_desktop.jpg', type: 'jpeg', quality: 80 });
}"
git add .scratch/evidence/<task-slug>/
Evidence is saved as JPEG (not PNG) to keep repo size down.
When completing a backlog task, append a note: Evidence: .scratch/evidence/<task-folder>/
Fallback: If visual-check.sh can't do what you need (e.g. clicking elements, filling forms, checking specific computed styles), fall back to raw playwright-cli commands. But always try visual-check.sh first.
python3 -m http.server to serve the file (playwright-cli blocks file:// URLs)playwright-cligetBoundingClientRect().width for all elements matching the selectorWhen visual-check.sh isn't enough and you need raw playwright-cli commands:
In CI, containers, or any environment running as root, Chromium refuses to launch
with sandboxing enabled. The visual-check.sh script handles this automatically,
but if you call playwright-cli directly you must set:
export PLAYWRIGHT_MCP_SANDBOX=false
before running playwright-cli open. This is safe on macOS too (ignored when
sandboxing works natively).
The globally installed playwright-cli (from @playwright/cli) is the correct
binary. Do not try to run it via npx playwright-cli — that resolves to a
different (non-existent) package.
playwright-cli blocks file:// URLs. Always serve files via a local HTTP
server first:
python3 -m http.server 18765 --directory /path/to/dir &
playwright-cli open http://localhost:18765/file.html
# ... do your work ...
playwright-cli close
kill %1
The session-start hook (session-start.sh) ensures Chromium is available.
If you hit "browser not found" errors, the hook likely didn't run. You can
manually fix it:
# Find Playwright's cached Chromium and symlink it (Linux only)
CHROME=$(find ~/.cache/ms-playwright -name "chrome" -path "*/chrome-linux/*" -type f | head -1)
mkdir -p /opt/google/chrome && ln -sf "$CHROME" /opt/google/chrome/chrome