Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

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.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
08.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
10
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
24
Przestarzałość

Brak sygnałów. Repozytorium zmienione 08.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 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

  1. Applies when / does not apply
  2. Rules
  3. Procedure
  4. Traps
  5. Done when
  6. References
  7. Sources
Sekcje z nagłówków SKILL.md, w oryginale · 244 linii, 2 591 słów
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

RepozytoriumWynikLicencja
Ta strona · Rene-Roscher/skills90Apache-2.0
srstomp/pokayokay100MIT
markoblogo/abvx-agent-skills90MIT

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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.