Web Quality Gatekeeper

A GitHub Action and npm CLI for browser smoke checks, accessibility scans, Lighthouse budgets, and visual comparisons. Each run produces an HTML report plus stable JSON and Markdown artifacts for CI.

Examples target 5.0.0 and require its publication before use. Check Releases and npm for availability. Read the migration guide when upgrading a native configuration.

Use the GitHub Action Open the sample report

GitHub Action	Targets `@v5`
Local CLI	Install from npm with Node.js 22.19 or later

What it checks

Playwright navigation and runtime errors
axe-core accessibility violations
Lighthouse performance budgets
Pixel-level visual differences
Screenshot capture
Multi-page rollups and trend history

Web Quality Gatekeeper report showing audit status and category scores — Report from the committed 3.2.4 fixture run. Open the HTML report or summary JSON.

GitHub Actions

Add the stable major tag to a workflow. The policy input is optional; this example uses the Action defaults.

- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
  with:
    persist-credentials: false
- id: wqg
  uses: Jahrome907/web-quality-gatekeeper@v5
  with:
    url: https://your-site.example
    baseline-dir: .github/web-quality/baselines

- name: Upload audit artifacts
  if: always() && steps.wqg.outputs.bundle-complete == 'true' && (steps.wqg.outputs.sensitive-audit == 'false' || env.WQG_ALLOW_SENSITIVE_OUTPUTS == 'true')
  uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
  with:
    name: wqg-artifacts
    path: ${{ steps.wqg.outputs.artifact-paths }}
    if-no-files-found: error

See the complete consumer workflow for optional settings.

Security: Authenticated and internal audits can contain sensitive page content. Keep artifact uploads disabled unless the output is deliberately safe to share.

Visual comparison is enabled by default. Run --set-baseline to write the current screenshots, review and commit those images, then run normally. A missing baseline fails; --no-fail-on-visual only permits completed visual diffs. For an audit without visual comparison, set toggles.visual to false in the configuration. The upload list contains only completed audit output; it excludes unrelated files and the external baseline directory.

A navigated document returning HTTP 400 or higher fails the audit. Lighthouse also rejects missing required measurements rather than substituting values. Console and runtime-error counts are diagnostics, not standalone default gates.

Install the CLI

The npm package is available for Node.js 22.19 or later.

npm install --save-dev web-quality-gatekeeper@^5
npx playwright install chromium
npx wqg audit https://your-site.example --set-baseline --baseline-dir .github/web-quality/baselines
# review the resulting baseline images, then commit them
npx wqg audit https://your-site.example --baseline-dir .github/web-quality/baselines

Reproduce the proof

Read the project-site case study for measured audits of two real site revisions and a controlled regression that fails the accessibility gate.

Follow the fixture run guide or review the public comparison protocol.

Version 5 uses pixelmatch exclusively; published 4.x releases are unchanged. See the migration notes and measurements before upgrading a native configuration.