Accessibility reports and retest tracking for QA teams and agencies.

Tester guide: scan, review and retest

Welcome to Gatekeeper Q A. This guide shows a real browser scan, a saved review, a report export, and a comparison after a fix. We use our own demonstration page. These are captured steps with pauses shortened, and synthetic narration. Automated checks support human testing; they do not certify accessibility.

1. Enter an authorized public page

Open scan dot gatekeeper Q A dot com. Enter one public page you own or have permission to test. Our target is slash guide dash demo. The hosted scanner needs a public address. Use the developer C L I for localhost. This recording is already signed in, so the report can be retained in the account.

2. Confirm permission and run

Confirm the permission checkbox, then choose Run accessibility scan. Additional page U R Ls are optional and use your plan allowance. A scan checks the initially loaded page, not every linked page or a signed-in journey. Wait for the result. If execution is incomplete, inspect the limitation and retry; do not treat it as a pass.

3. Read the result before making changes

Our first completed scan failed. It found one critical button-name violation affecting one element, with zero scan errors. Open the finding and read why it matters. A screen-reader user needs to know what the button does. A failed accessibility gate is useful evidence, not a reason to hide the result.

4. Expand the element evidence

Choose View locations and scan evidence. Here the selector is checkout, and the captured button has no text. Send the rule, location, observed page state and proposed fix to the developer. For this example, visible Checkout text is appropriate. Always verify the meaning of a label in the actual page.

5. Save and open your report

Find the result under My reports. Rename it with a useful baseline label, then choose Open report. Guests can use Save report and complete sign-in; that sign-in step is not shown here. Check that the intended report appears before leaving the page. Saved reports have an expiry, so download evidence you need to retain.

My reports
Rename: Tutorial — before button fix
Open report
Saved tester review
Choose the finding or manual check

6. Record what you actually tested

In Saved tester review, select the finding or manual check. Set a tracking status, enter a reviewer name, and describe your test steps and evidence. Choose Save review. We kept this finding open. Our first keyboard attempt did not produce the expected message, and the note says so. Screen-reader testing remains outstanding.

7. Export the right copy

Choose Open reviewed report slash save P D F to include saved notes. It opens separately, so your working page stays available. Use its Print slash save as P D F control and your browser print dialog. Original downloads remain unchanged. The reviewed J S O N and review C S V are separate ways to retain your notes.

8. Fix the page and check its behavior

The developer added visible Checkout text and corrected the demonstration script loading. On the updated page, the button now receives focus and Enter displays the no-payment confirmation. That is one observed interaction, not a complete manual assessment. Check keyboard order, visible focus, screen-reader behavior, zoom and relevant page states for your own application.

9. Rescan the same scope

Return to My reports and choose Rescan on the baseline. Review the U R L and confirm permission again. Our fresh scan of the same page passed. Rename it as the after report. A pass means this automated gate found no blocking result in that scan. It does not establish full W C A G conformance.

10. Compare, then verify

In Compare reports, select the earlier baseline and the later retest. Choose Compare findings. Our comparison shows one finding no longer detected, zero newly detected, and zero still detected at the same location. Expand the result and verify it manually before closing the issue. Preserve both reports and your review evidence.

Your repeatable testing loop

Use the same loop on each authorized page: scan, inspect evidence, record manual observations, make a fix, and retest the same scope. Keep incomplete results and unreviewed checks visible. The developer guide covers local commands and GitHub Actions. Visit the testing guide on gatekeeper Q A dot com for the written workflow.

SCAN  →  REVIEW  →  FIX  →  RETEST
Keep the same page scope.
Record observations, not assumptions.
Export evidence before expiry.
PASS is not an accessibility certification.

Developer guide: CLI and GitHub Actions

This guide covers Gatekeeper Q A from the command line and in GitHub Actions. We will configure an explicit page, inspect a failing result, fix a button label, and retrieve a successful retest. Browser captures are from real runs. Command cards are readable instructions; local result cards summarize retained execution logs. Narration is synthetic.

1. Install the pinned CLI

Use Node J S twenty four with N P M. In a new project directory, initialize package dot J S O N, install Gatekeeper Q A C L I version zero point three point zero, then install Playwright Chromium. In an existing project, skip N P M init. The clean GitHub runner installation shown later also verifies this published package.

node --version
npm init -y
npm install --save-dev --save-exact @gatekeeperqa/cli@0.3.0
npx --no-install playwright install chromium

2. Start your app and configure pages

Start your application using its normal development command, and wait until its page is available. Save gatekeeper Q A dot J S O N with the actual U R L. This example uses localhost port three thousand. Replace that address if your app uses another port. The C L I checks explicit U R Ls, not a whole-site crawl.

gatekeeperqa.json
{
  "urls": ["http://127.0.0.1:3000/"],
  "failOn": ["critical", "serious"],
  "warnOn": ["moderate", "minor", "unknown"],
  "timeoutMs": 30000
}

3. Run a baseline scan

Run the C L I with your configuration and a separate before output directory. Open report dot H T M L after the command finishes. In our local demonstration, the unnamed button produced a critical button-name finding and exit code one. The retained transcript records that real result; the equivalent N P X command is shown here.

npx --no-install gatekeeperqa --config gatekeeperqa.json --output reports/before

Recorded local result (CLI build 0.3.0):
GatekeeperQA: FAIL
Exit code: 1
button-name · critical · 1 affected occurrence

4. Read reports and exit codes

Exit zero does not mean zero accessibility issues. In GatekeeperQA CLI version 0.3.0, exit zero means pass or warning. Exit one means the report status is fail. Exit two means a configuration or runtime error. Always read the report. Automated checks do not replace human testing.

reports/before/report.html
reports/before/report.json
reports/before/report.md
reports/before/report.xml

Bash: echo $?     PowerShell: $LASTEXITCODE

5. Fix, then preserve a separate retest

Give the button meaningful visible text and run the same scope into an after directory. Our local retest returned pass and exit zero. Preserve the baseline. Reproduce the affected page state and test the interaction manually, including a screen reader. A passing automated result does not prove the entire experience is accessible.

Before: <button id="checkout"></button>
After:  <button id="checkout">Checkout</button>

npx --no-install gatekeeperqa --config gatekeeperqa.json --output reports/after

Recorded local result: PASS · exit 0

6. Add the manual GitHub workflow

Copy the downloadable accessibility workflow into dot github slash workflows slash accessibility dot Y A M L in your repository. Commit it to the default branch so Run workflow is available. The template uses a manual trigger, read-only repository permission, Node twenty four, the pinned C L I, and seven-day report artifacts. It does not deploy your application.

.github/workflows/accessibility.yml

Trigger: workflow_dispatch
Input: target_url
Install → Scan → Save reports → Enforce result

Use a public deployed page you are authorized to test.

7. Choose the branch and public target

Open Actions, select the workflow, and choose Run workflow. Select the branch containing your intended workflow version and enter an authorized public page. Our recording uses an existing verification workflow on the review branch, with C L I zero point three point zero. The downloadable template has the same scan and artifact steps, with a manual trigger.

8. Inspect a genuine failed gate

The first GitHub run failed on the original demonstration page. Expand Scan authorized U R L and Enforce result to see the result and exit code. Save reports runs before the gate is enforced, so a failed accessibility result still leaves evidence. Open the artifact on the run summary rather than relying on the red status alone.

9. Retrieve the fixed-page result

After publishing the button fix, we ran the same workflow and public U R L again. This run succeeded, with one report artifact. Open the accessibility job for its scan output, then download accessibility reports from the summary. Extract the archive and open report dot H T M L; retain the machine-readable files for your tools.

10. Keep the evidence after the runner stops

The saved artifact contains the generated report files. Download it before its seven-day retention ends. The runner installed the public N P M package and Chromium cleanly; the two recorded runs took fifty four and forty one seconds. Check your own GitHub plan for runner billing. A completed job proves this run, not every page or state.

11. Adapt CI carefully

For pull-request testing, first build and start the changed application on the runner, or deploy a preview and wait for it. Point the scan at that changed version. A manual scan of production is not a pull-request check. Add the appropriate trigger and branch protection deliberately. This guide does not configure a P R bot or automatic comments.

Before enforcing pull-request checks:
1. Build and start the changed application.
2. Wait until its URL is ready.
3. Scan that URL and preserve reports.
4. Enforce the result after artifact upload.
5. Configure required checks for your repository.

Use automation and human review together

You now have a repeatable C L I and Actions workflow: explicit scope, a clear gate, report artifacts, and a separate retest. Use the browser tester guide to record manual observations and compare saved reports. Download the workflow and read the developer quick start on gatekeeper Q A dot com. Keep human testing part of every release.