browser-verification
/browser-verification
Sprawdza zmiany interfejsu w headless przeglądarce: zrzuty elementów, kontrast, rozmiar celów i błędy konsoli przed zgłoszeniem.
- Autor
- Rene-Roscher ↗
- Repozytorium
- skills ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 08.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 10
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 24
Brak sygnałów. Repozytorium zmienione 08.11.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/measure-check.py
Co robi i kiedy
Sprawdza zmiany interfejsu w headless przeglądarce: zrzuty elementów, kontrast, rozmiar celów i błędy konsoli przed zgłoszeniem.
Oryginalny opis (EN)
Proves UI changes in a real headless browser before reporting done: served-build preflight, deterministic waits, element screenshots, overflow, contrast and target size as numbers, no console errors. Use when asked to verify, screenshot or visually check a page, confirm a frontend fix, check dark mode or responsive layout, or write browser tests. Not for UI design or the user's own browser.
Jak działa
- Applies when / does not apply
- Rules
- Procedure
- Traps
- Done when
- References
- Sources
Podgląd SKILL.md
---
name: browser-verification
description: "Proves UI changes in a real headless browser before reporting done: served-build preflight, deterministic waits, element screenshots, overflow, contrast and target size as numbers, no console errors. Use when asked to verify, screenshot or visually check a page, confirm a frontend fix, check dark mode or responsive layout, or write browser tests. Not for UI design or the user's own browser."
license: Apache-2.0
compatibility: "Playwright Test 1.61 or later, or the Pest 4 browser plugin. Python 3 for the bundled measurement checker. Any server-rendered or single-page frontend."
metadata:
author: "Rene Roscher"
paths:
- "**/tests/Browser/**"
- "**/tests/e2e/**"
- "**/e2e/**"
- "**/*.spec.ts"
- "**/*.e2e.ts"
- "**/playwright.config.*"
---
# Browser verification
A UI claim without a browser run is unverified. This skill decides how an agent proves a UI change in a real
headless browser and what counts as evidence: measured numbers and element screenshots, never "looks fine".
Runner syntax stays in the Playwright and Pest docs linked under Sources. The failure it prevents: a fix
reported as done that never changed what the user sees.
## Applies when / does not apply
- Applies: verifying, screenshotting or visually checking a page; confirming a frontend fix; contrast,
overflow, fit, dark mode or responsive checks; writing or fixing browser tests (`tests/Browser`, `*.spec.ts`);
any UI task about to be reported as finished.
- Does not apply: unit or feature tests that need no browser, typecheck errors, UI design, performance budgets
or load tests, scraping other sites, and anything in the user's own browser, mail or logged-in accounts.
- Where things render and why (SSR, CSP, i18n rules) is decided in `web-architecture`.
## Rules
- [invariant] Report only what was seen working. A UI item is done only with browser evidence: the command,
the result, the artifact path. Otherwise it is reported as "implemented, not verified in a browser", with
the reason and what was checked instead (source read, unit test, server-side page test). Why: items
reported as fixed did not change the user-visible symptom. Test: every UI item in the report carries a
command, a result and an artifact path that exists, or the words "not verified in a browser". Status
vocabulary follows `verify-before-done`.
- [invariant] Never use the user's browser, profile, cookies or accounts. Launch a fresh browser with a fresh
context; never attach to a running browser, never point at a real profile directory, never import cookies.
Why: a real profile mixes the user's sessions into the test and can act on their accounts. Test: a guard
over test files and CI config fails on `launchPersistentContext(`, `connectOverCDP(` and `--user-data-dir`
outside an allowlisted CI fixture.
- [default] Run every browser headless. Headed mode is a local debugging choice the user makes, not something
the agent switches on. Trade-off: headless rendering differs from a user's browser in a few known places,
which the report lists as not verifiable headless. Deviate only with an ADR that names this trade-off.
Proof: the same guard fails on `headless: false`, `--headed` and `headed()` in committed files. Source:
https://playwright.dev/docs/debug ("Playwright runs browsers in headless mode by default", verified
2026-10-31).
- [invariant] Verify what is served, not what is in the source tree. Before the first assertion, run the
preflight and paste its output into the report: built bundle or dev server, the served artifact contains
the change, no dev-host mock fallback, no dev-server error overlay. Browser tests run against built assets
and skip with an actionable message when a dev-server marker is present (Laravel's Vite hot file, by
default `public/hot`). Why: a stale SSR cache served old markup, dev fixtures sent plain strings where
production sends objects, and an unreachable HMR host left the app unmounted. Test: the preflight greps
the served page or asset for the new string or class and fails when it is absent; the shared setup skips
when the hot file exists.
- [invariant] Fixtures are isolated, seeded and side-effect free. Each test creates its own tenant and user
through the application's real creation path, passes every gate a real user passes (terms, onboarding,
welcome dialogs), reuses the session as stored state, and cleans up. Never a shared development database
with ad-hoc users, never production data, never a code path that notifies real people. Why: gate dialogs
dimmed the page and falsified every colour measurement, and logins landed on consent pages. Test: one shared
fixture helper used by every browser test; a test asserts that the mail, SMS, chat and webhook transports
of the test environment are fakes. See `safe-actions`.
- [invariant] The browser suite runs in its own environment and starts clean every run. It gets its own ports,
its own database and its own build output, and never reuses the developer's dev server, dev database or dev
build marker (Laravel's hot file); a global setup resets the state the suite depends on (fresh schema and seed
in the test database, cleared cache, including rate-limit counters kept in it), and every limit a test can reach
is configurable through the environment with a test value. Why: counters in a cache-backed rate limiter outlive
a run, so each test passed alone and the full suite failed at the limit on the next run; a suite that shares the
dev server or dev database tests leftovers and breaks the developer's setup. Test: run the full suite twice in a
row with the dev stack running; both runs pass and the dev database is unchanged; `reuseExistingServer` is not
`true` against a port the dev server uses. Source: Playwright `webServer.reuseExistingServer`, "If `true`, it
will re-use an existing server on the `port` or `url` when available."
(https://playwright.dev/docs/test-webserver); Laravel rate limiting "utilizes your default application cache"
(https://laravel.com/docs/12.x/rate-limiting); both verified 2026-11-05.
- [invariant] Every browser test asserts the absence of failure: no JavaScript errors, no failed requests to
your own origin, zero CSP violations, exact counts where counts matter (one toast, one POST per submit), and
no known failure signature (the fallback sentence shown when data did not arrive, a prop rendered as a DOM
attribute). Why: a double submit sent two POSTs while the positive assertions passed. Test: a shared
after-each helper runs the error, network and CSP checks; a request counter records requests per action.
Source: https://pestphp.com/docs/browser-testing (`assertNoJavaScriptErrors`, `assertNoConsoleLogs`;
verified 2026-10-31).
- [invariant] Wait for the condition you are about to assert, then read or count. No fixed timeouts as
synchronization (`waitForTimeout`, `sleep`, `usleep`, a fixed `wait()`). Why: counting an empty toast
container right after a click passes no matter how many toasts arrive later. Test: a guard over test files
fails on those calls outside a `debug/` helper. Source:
https://playwright.dev/docs/api/class-frame#frame-wait-for-timeout ("Tests using the timer in production
are going to be flaky") and https://playwright.dev/docs/best-practices (web-first assertions), verified
2026-10-31.
- [invariant] Measure; do not eyeball. Decide visual questions with computed values from the real browser and
compare each number with its threshold before writing a conclusion: text contrast at least 4.5:1, large
text and UI components at least 3:1, pointer targets at least 24 x 24 CSS px unless an exception applies,
no horizontal overflow beyond 1 px for the document and each container (including `overflow: hidden`
ones), fit at the project's smallest supported viewport. At least one element must match before "no
overflow" means anything. Why: a checker that skipped `overflow: hidden` reported clean while columns
overflowed by 95 px, and grey text that looked fine measured 2.56:1. Test:
`python3 "${CLAUDE_SKILL_DIR}/scripts/measure-check.py" check [artifact].json` exits 0, and its
`self-test` passes. Source: https://www.w3.org/TR/WCAG22/ (1.4.3, 1.4.11, 2.5.8), verified 2026-10-31.
- [invariant] Evidence is element screenshots plus numbers, kept as artifacts. Screenshot the element under
test (`locator.screenshot()`, or `screenshotElement()` in the Pest plugin), never a full-page shot cropped
by coordinates. Save screenshots and measurement JSON under a versioned path that CI uploads, not in a temp
directory. Why: coordinate crops hid the element in question, and screenshots in a temp directory were
deleted before anyone could repeat the check. Test: the CI job uploads the artifact directory, and every
path the report names exists. Source: https://pestphp.com/docs/browser-testing (verified 2026-10-31).
- [default] Select copy-driven elements by `data-testid`, and use role plus accessible name where the
semantics are what you test. Never select by translatable text, class chains or DOM structure. Trade-off:
test IDs add attributes to production markup and say nothing about accessible names. Deviate only with an
ADR that names this trade-off. Source: https://playwright.dev/docs/locators#locate-by-test-id (default
attribute `data-testid`, verified 2026-10-31).
- [default] For push-to-deploy apps, check the production bundle before pushing: build it in a temporary copy,
run it against a non-production backend, and run the browser checks there. A preview deployment satisfies
this rule. Trade-off: a production build per change. Deviate only with an ADR that names this trade-off.
Proof: the report names the build command and the URL the checks ran against.
- [default] Know where the harness differs from a user's browser and check those parts separately. Playwright's
headless Chromium hides scrollbars, mutes audio, reports a fine pointer with hover, and may render through a
software GL backend; WebKit in Playwright is not Safari. Trade-off: those behaviours stay unverified in the
automated run. Deviate only with an ADR that names this trade-off. Source:
https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/chromium.ts
(headless launch arguments, checked in 1.61.1 and 1.64.1, 2026-10-31).
- [default] Use the browser only for what server tests cannot see: props reaching components, client-side
storage, layout, counts of events, toasts and requests, permission-filtered option lists, dialog gating, CSP.
Payloads and authorization belong to feature tests. Trade-off: a behaviour seen only in the browser has no
fast server-side check. Deviate only with an ADR that names this trade-off. Proof: the report maps each
browser test to one of these categories.
- [default] Run an accessibility scan and walk the primary flow by keyboard on every changed page. Trade-off:
scans add run time and catch only part of WCAG. Deviate only with an ADR that names this trade-off. Source:
https://pestphp.com/docs/browser-testing (`assertNoAccessibilityIssues`, default level 1) and
https://playwright.dev/docs/accessibility-testing (`@axe-core/playwright`; automated tests cannot find every
violation), verified 2026-10-31.
- [default] A change to markup, tokens or states updates the browser tests that assert them in the same commit,
and the suite runs before that commit. Trade-off: a design change is not done until its tests are. Deviate
only with an ADR that names this trade-off. Proof: the commit that changes a selector, a state style or a
hidden element also changes the test; no "fix tests" commit follows a design commit.
- [default] Finish edits before a browser run. When a dev build plugin regenerates code from backend files,
write an import and its use in the same edit; an error overlay is a setup error, so rerun the generator and
then the test instead of changing the test. Trade-off: a rerun after every edit batch. Deviate only with an
ADR that names this trade-off. Proof: the preflight checks for an overlay before the first interaction.
- [default] Cover the engines and viewports your users have: public pages in Chromium, Firefox and WebKit plus
one mobile emulation; dashboards in Chromium at the project's viewport set and in dark mode if the app offers
it. Trade-off: CI time per engine. Deviate only with an ADR that names this trade-off. Proof: the CI matrix
and the report list engines and viewports per item.
## Procedure
1. Gate: check that a headless browser can run here (runner installed, browser binaries present). If not,
stop. Report "not verified in a browser", list what was checked instead, and ask before installing
anything.
2. Preflight: run the checks in [references/preflight.md](references/preflight.md) and keep the output.
3. Environment: the suite's own ports, database and build; global setup resets schema, seed and caches.
Fixture: create the tenant and user through the real path, pass the gates, pin locale and theme, store the
session.
4. Run headless. Wait for each condition before reading or counting.
5. Assert the absence of failure: errors, failed requests, CSP violations, exact counts, failure signatures.
6. Measure with the collector from [references/measurement.md](references/measurement.md), save the JSON and
element screenshots to the artifact directory, then run
`python3 "${CLAUDE_SKILL_DIR}/scripts/measure-check.py" check [artifact].json`.
7. Report per item with [references/evidence-format.md](references/evidence-format.md), including what was not
verified.
## Traps
- A stale SSR cache served old markup, and correct CSS was doubted twice. Detect: grep the served HTML for the
change before judging the CSS.
- Dev fixtures sent plain strings where production sends localized objects, so a fix verified against dev data
rendered `[object Object]` in production. Detect: fixtures built through the real backend path.
- The HMR host was unreachable from the headless browser, the app never mounted, and every test timed out on a
blank page. Detect: the dev-server marker skip.
- Each test passed alone and the full run failed with "too many attempts": a rate-limit counter in the database
cache survived from the previous run. Clear the cache in global setup and read the limit from the environment.
- Design changes left tests asserting an old border, an old focus style and an input that was now hidden. Change
the test in the same commit as the design.
- A count read right after a click returned zero toasts and passed. Wait for the expected count instead.
- A component fell back to a generic sentence when its data was missing, and every positive assertion still
passed. Assert the fallback sentence is absent.
- A half-finished edit broke a code generator; the dev server showed the error overlay to the test browser,
which surfaced as a 30-second click timeout.
- A scrollbar style existed for months without ever rendering in headless runs. A video whose `currentTime`
advanced in the headless run showed only black frames in browsers that decode on the GPU. Read pixels from a
drawn frame instead ([references/harness-differences.md](references/harness-differences.md)).
## Done when
- Every UI item in the report has a command, a result, an artifact path, and the engines and viewports it ran
on, or is marked "not verified in a browser" with the reason.
- The preflight output is in the report and shows the served artifact contains the change.
- The absence-of-failure checks passed, and `measure-check.py check` exited 0 on the measurement JSON.
- No fixed waits, no headed mode, no user profile in the committed tests.
- The suite ran twice in a row on its own ports and database, and passed both times.
- Behaviours the harness cannot show (scrollbars, GPU video, real Safari) are listed as not verifiable
headless.
## References
- [references/preflight.md](references/preflight.md): load before the first browser run in a session, and
whenever results contradict the source.
- [references/waits-and-selectors.md](references/waits-and-selectors.md): load when writing or fixing a flaky
browser test.
- [references/measurement.md](references/measurement.md): load for contrast, overflow, fit, target size, or any
"does it look right" question.
- [references/fixtures-and-identities.md](references/fixtures-and-identities.md): load when setting up the suite's
own ports, database and global setup, and for authenticated pages, gated flows, dark mode, locale pinning and
cleanup.
- [references/prod-bundle-check.md](references/prod-bundle-check.md): load for push-to-deploy SSR or static
sites, or when verifying the production build before a release.
- [references/harness-differences.md](references/harness-differences.md): load for scrollbars, media, GPU,
WebKit and Safari, hover and pointer media queries.
- [references/evidence-format.md](references/evidence-format.md): load when writing the verification report.
- [references/guard-artifacts.md](references/guard-artifacts.md): load when adding the shared setup, lint
guards and CI job that enforce these rules.
- [scripts/measure-check.py](scripts/measure-check.py): run with `check`, `contrast` or `self-test`; `--help`
lists the options.
## Sources
- https://playwright.dev/docs/debug: browsers run headless by default; `headless: false` turns it off, verified
2026-10-31.
- https://playwright.dev/docs/api/class-frame#frame-wait-for-timeout: fixed waits are for debugging only,
verified 2026-10-31.
- https://playwright.dev/docs/best-practices: web-first assertions, user-facing locators, verified 2026-10-31.
- https://playwright.dev/docs/locators#locate-by-test-id: `getByTestId` uses `data-testid` by default,
configurable, verified 2026-10-31.
- https://playwright.dev/docs/accessibility-testing: `@axe-core/playwright` and `AxeBuilder`; automated testing
cannot detect all WCAG violations, verified 2026-10-31.
- https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/chromium.ts:
headless Chromium gets `--hide-scrollbars`, `--mute-audio` and hover and fine-pointer blink settings; same in
the published 1.61.1 and 1.64.1 bundles, checked 2026-10-31.
- https://pestphp.com/docs/browser-testing: `assertNoJavaScriptErrors`, `assertNoConsoleLogs`,
`assertNoAccessibilityIssues`, `screenshotElement`, `assertScreenshotMatches`, `--headed`, `inDarkMode`,
`withLocale`, `--browser firefox|safari`, verified 2026-10-31.
- https://www.w3.org/TR/WCAG22/: contrast 4.5:1 and 3:1 (1.4.3), non-text contrast 3:1 (1.4.11), target size
24 x 24 CSS px (2.5.8), verified 2026-10-31.
- https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html: target size exceptions, verified
2026-10-31.
- https://playwright.dev/docs/test-webserver: `webServer`, `reuseExistingServer`, verified 2026-11-05.
- https://laravel.com/docs/12.x/rate-limiting: the rate limiter uses the default cache store unless `limiter` is
set, `RateLimiter::clear`, verified 2026-11-05.
- https://laravel.com/docs/12.x/vite: the `@vite` directive detects the dev server through the hot file;
`Illuminate\Foundation\Vite` defaults it to `public/hot` (framework 12.x source), verified 2026-10-31.
Pliki w paczce (10)
- SKILL.md 19 KB
- references/evidence-format.md 2 KB
- references/fixtures-and-identities.md 5 KB
- references/guard-artifacts.md 5 KB
- references/harness-differences.md 3 KB
- references/measurement.md 8 KB
- references/preflight.md 3 KB
- references/prod-bundle-check.md 2 KB
- references/waits-and-selectors.md 3 KB
- scripts/measure-check.py 11 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · Rene-Roscher/skills | 90 | Apache-2.0 |
| srstomp/pokayokay | 100 | MIT |
| markoblogo/abvx-agent-skills | 90 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 50366339c9c4 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 1 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100wowsir
Testuje strony i przepływy w bezgłowej przeglądarce wowsir, sprawdza zmiany interfejsu i odtwarza błędy frontendu. - 100browser-qa
Uruchamia headless przeglądarkę na lokalnie serwowanym UI i zbiera zrzuty ekranu, raportując kroki jako PASS, FAIL lub BLOCKED wraz z tekstem DOM i błędami konsoli. - 90verify-ui
Sprawdza zmianę interfejsu w przeglądarce: uruchamia serwer, robi zrzuty ekranu w telefonie i na komputerze oraz szuka błędów układu. - 90browser-qa
Sprawdza zmiany interfejsu w prawdziwej przeglądarce: trasy, kluczowe interakcje, dwa lub więcej rozmiarów ekranu i błędy konsoli. - 95Browser
Debuguje frontend w przeglądarce: zbiera logi konsoli, żądania sieciowe i błędy od razu, bez dodatkowej konfiguracji. - 90e2e-verify
Weryfikuje pull request testami E2E w przeglądarce przed scaleniem, także sprawdzając wizualnie zmiany w interfejsie.