Docs

CI browser consistency checks

Browser consistency checks belong in CI after a preset is chosen. The goal is to fail fast when user agent, viewport, DPR, locale, timezone, or network assumptions drift before release.

What should CI prove?

CI should prove that the browser fixture still matches the preset your team committed. A scan is useful during setup; a repeatable CI check is what prevents silent drift across browser upgrades, proxy changes, and regional test runners.

Which artifact should be committed?

Commit either the generated Playwright `use` block or the JSON preset. Store it beside the test project and review changes like any other production fixture.

Recommended workflow

  1. Run a local scan on the target page from the browser profile you plan to use for QA.
  2. Fix the first ranked mismatch before tuning lower-impact signals.
  3. Export the closest preset or copy the suggested Playwright `use` block.
  4. Commit the preset beside the Playwright project so changes are reviewed.
  5. Add a CI threshold check with `--fail-under` so drift fails before release.
browser-fidelity audit https://example.com \
  --preset desktop-chrome-us \
  --fail-under 90 \
  --json

name: browser-fidelity

on:
  pull_request:
  push:
    branches: [main]

jobs:
  browser-fidelity:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm exec browser-fidelity audit "$BROWSER_FIDELITY_TARGET_URL" --preset desktop-chrome-us --fail-under 90 --json
        env:
          BROWSER_FIDELITY_TARGET_URL: https://example.com

When should the build fail?

Fail the build when the scan cannot run, when required metadata pages are unreachable, when a required share flow fails in production QA, or when the CLI score is below the selected `--fail-under` threshold. The suggested Playwright config should still include core fields such as user agent, viewport, device scale factor, locale, and timezone.

What should stay out of CI?

Do not commit browser cookies, personal profiles, proxy credentials, or environment secrets. CI should verify observable consistency, not copy a human browser session.