code-yeongyu/oh-my-openagent / packages/shared-skills/skills/visual-qa
visual-qa
VerifiedRuns rigorous visual QA across web, terminal, and paginated surfaces: an Apple HIG-based checklist, paired light/dark captures at phone and desktop widths, screenshot evidence, and a per-item PASS/FAIL verdict. Use for any UI build or change, or when asked whether a page, component, or TUI looks right or follows the platform's design guidelines.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 3.2 KB |
| SKILL.md | skill md | 45.7 KB |
| references/browser-setup.md | markdown | 5.6 KB |
| scripts/ansi.test.ts | script | 1.1 KB |
| scripts/ansi.ts | script | 496 B |
| scripts/cli.test.ts | script | 2.9 KB |
| scripts/cli.ts | script | 2.5 KB |
| scripts/east-asian-width.test.ts | script | 1.9 KB |
| scripts/east-asian-width.ts | script | 3.0 KB |
| scripts/image-diff.test.ts | script | 2.5 KB |
| scripts/image-diff.ts | script | 3.8 KB |
| scripts/png-crc.ts | script | 707 B |
| scripts/png-decode.test.ts | script | 1.5 KB |
| scripts/png-decode.ts | script | 5.5 KB |
| scripts/png-synth.ts | script | 1.7 KB |
| scripts/skill-doc-fields.test.ts | script | 1.6 KB |
| scripts/tui-grid.test.ts | script | 1.9 KB |
| scripts/tui-grid.ts | script | 2.7 KB |
| scripts/types.ts | script | 1.3 KB |
| scripts/visual-qa.mjs | script | 15.8 KB |
references/browser-setup.md
View on GitHub# Browser setup (Web capture)
Capture with omowright from the js-eval kernel. The library is staged inside the `browser` skill;
load it once per session:
```js
const { loadOmowright } = await import("<browser-skill-root>/scripts/omowright.mjs")
const { omowright } = await loadOmowright()
```
## Owned engine (default for QA) - the capture matrix
A browser your code launches, with a task-owned profile, pinned viewport and no user state.
`connectPipe` opens no listening port and reaps the process on `close()`. One loop produces the
whole matrix the skill requires: phone (true mobile emulation) and desktop, light and dark, top
and scrolled-to-end, plus the reduced-motion variant for motion frames. `page.screenshot()` is a
PNG of the page itself, so no browser chrome can appear in it.
```js
// js-eval cell; urls and outDir belong to this QA run.
const { mkdtempSync, rmSync } = await import("node:fs")
const profile = mkdtempSync(`${(await import("node:os")).tmpdir()}/visual-qa-`)
const browser = await omowright.connectPipe({
browserPath: chromeBinary, // installed Chrome, Chromium, CloakBrowser or chrome-headless-shell
browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
storageRoot: profile,
})
const media = (page, sid, scheme, motion) => page.cdp.send("Emulation.setEmulatedMedia", {
features: [{ name: "prefers-color-scheme", value: scheme }, { name: "prefers-reduced-motion", value: motion }],
}, sid)
let page
try {
page = await browser.newTab("about:blank")
const sid = await page.resolveSessionId()
for (const [route, url] of Object.entries(urls)) {
for (const device of ["iphone-14", "desktop-1440"]) { // 390 @ DPR 3, mobile + touch (overlay scrollbars); 1440 @ DPR 1. Add { width: 1920, height: 1080, deviceScaleFactor: 1, mobile: false, hasTouch: false } for page layouts.
await omowright.emulate(page, device)
for (const scheme of ["light", "dark"]) {
await media(page, sid, scheme, "no-preference")
await page.goto(url, { waitUntil: "load" }) // then wait for the page's own ready state (a locator, waitForURL, network snoop), never a sleep
await Bun.write(`${outDir}/${route}-${device}-${scheme}-top.png`, await page.screenshot())
await page.evaluate(() => window.scrollTo(0, document.documentElement.scrollHeight))
await Bun.write(`${outDir}/${route}-${device}-${scheme}-end.png`, await page.screenshot())
}
}
}
// Motion frames: drive the state (hover/press/open), then capture rest, ~100 ms and settled; repeat under
// media(page, sid, scheme, "reduce") for the reduced-motion pass.
} finally {
if (page) await omowright.emulate(page, null)
await browser.close()
rmSync(profile, { recursive: true, force: true })
}
```
Chrome must already be installed; report an absent executable rather than downloading a managed
browser. For bot-scored or WAF targets use `connectCloakProfile({ profileDir })` (CloakBrowser
with a pinned fingerprint seed) — the `browser` skill's `references/owned-engine/README.md`
covers it.
## Attached engine (authenticated pages)
When the capture needs the user's login, drive the browser they are signed into instead of
cloning its profile:
```js
const session = await omowright.connectBrowserSkill({ name: "visual-qa capture", focused: false })
const sync = async () => (await session.cooperate("sync")).context_id // BrowserSkill 0.4: one context per page action
try {
await session.navigate(url, { waitUntil: "load", context: await sync() })
await session.resize(1440, 900, { context: await sync() }) // desktop column of the matrix
await Bun.write(`${outDir}/${route}-1440-top.png`, (await session.screenshot()).buffer) // { buffer, width, height }
await session.emulate({ overrides: { width: 390, mobile: true }, context: await sync() }) // phone column; `off: true` restores
await Bun.write(`${outDir}/${route}-390-top.png`, (await session.screenshot()).buffer)
} finally {
await session.emulate({ off: true, context: await sync() })
await session.stop()
}
```
The attached engine follows the signed-in browser's own colour scheme; switch the OS or browser
theme between the light and dark passes, and record which theme each file carries.
NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
run the `browser` skill's `scripts/browser-install.mjs` for the browser the user actually uses
(from memory, or its detection; on `needsChoice` ask them and pass `--browser=<id>`), relay its
one human step, and wait — do
not fall back to the owned engine for an authenticated criterion.
## Capture at a fixed viewport
Match CSS viewport AND PNG dimensions: pin `deviceScaleFactor` through `emulate` (owned engine).
Attached `resize(width, height)` sets the window size only and leaves the device pixel ratio at the
user's display, so on the attached engine record the capture's DPR (PNG width / CSS viewport width)
and compare against a reference taken at that DPR. Never resize the PNG to force a pass; a 390-wide capture at desktop
DPR with classic scrollbars is not a phone capture. Wait for the specific page state (a locator,
a `waitForURL`, a `createNetworkSnoop(page).waitFor(...)`), not a sleep, then compare:
```sh
node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff reference.png actual.png
```
Inspect `dimensionsMatch` and `diffRatio`, then inspect the image. Close every browser and session
and the fixture server, even on a failed capture; remove the owned profile in the same `finally`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |