GatekeeperQA 教學：CI 無障礙檢查失敗後先保留證據再修正

A red accessibility check tells you that a gate failed. The useful next questions are: which element triggered it, what page state was tested, and what evidence will you compare after the change?

The workflow below keeps the original report, generates a separate retest report, and records manual observations alongside the automated result.

Disclosure: I maintain GatekeeperQA, the tool used here. The local CLI runs without a hosted account. Hosted storage and review features are separate, with plan and retention limits.

Keep two reports, not one overwritten folder

With Node.js 24 and an existing package.json, install the pinned CLI:

npm install --save-dev --save-exact @gatekeeperqa/cli@0.3.0
npx --no-install playwright install chromium

Create gatekeeperqa.json:

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

Start your app and wait until it is ready, then scan:

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

After implementing your change, run the same configuration against the updated app:

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

Use fresh directories for each attempt. A setup failure must not leave you interpreting an older report as the latest result.

Open each directory's report.html. Completed scans also produce JSON, Markdown and JUnit XML. The CLI does not directly export a PDF.

This configuration checks an explicitly listed page in its initially loaded state. It does not crawl the site or exercise login, dialogs, checkout, or other interactions. Use only targets you own or have permission to test.

In GitHub Actions, save evidence before enforcing the gate

If the scan exits nonzero, a normal subsequent step can be skipped. Separate evidence collection from the step that marks the job failed.

GatekeeperQA's complete GitHub Actions setup installs the published package, captures the scan exit code, uploads available report artifacts, and then enforces that result.

The important sequence is:

1. Run the scan and retain its exit code.
2. Upload the evidence even when the quality gate fails.
3. Fail the job when the captured result requires it.

Do not turn a failed scan into a successful check just to keep the artifacts. Setup failures may have no report; inspect the logs in that case.

In this CLI version, PASS and WARN exit with 0, FAIL with 1, and setup/configuration errors with 2. WARN still needs review. A gate result is not a compliance certificate.

Also check what the workflow actually targets. Scanning production does not test code that exists only in a pull request. For PR validation, run the checked-out app or scan that PR's deployed preview after it is ready.

Retest the same element and state

Consider an icon-only button:

<!-- Before: no accessible name -->
<button type="button" id="checkout">
  <svg aria-hidden="true" focusable="false"><!-- icon --></svg>
</button>

<!-- After: visible text names the action -->
<button type="button" id="checkout">
  <svg aria-hidden="true" focusable="false"><!-- icon --></svg>
  Continue to checkout
</button>

This is an illustrative fix, not a customer assessment. A subsequent scan may stop reporting the naming issue, but that alone does not verify keyboard activation, focus behavior, or the resulting checkout state.

Before closing the ticket, confirm that the button still exists and was included in the retest. Record the builds, URL, state, engine version and configuration. If those changed, explain the difference.

Write “no longer detected in this scan” when that is what you established. Record keyboard and screen-reader observations separately; leave checks you did not perform marked as not tested.

Give the next reviewer a reproducible handoff

Original report and finding:
Original build:
Updated build:
Page and starting state:
Element location and rule:
Automated retest result:
Keyboard observations:
Screen reader/browser and observations:
Checks not performed:
Reviewer and date:
Remaining issues:

GatekeeperQA's hosted review workflow can keep saved notes and prepare an editable GitHub issue draft. Its private finding links open the specific element in a retained report. Those links require the report owner's sign-in; pasting one into a team ticket does not grant teammates access. Include appropriately redacted evidence that your intended reviewer can actually read.

You can also keep this information in your existing tracker and retain the local reports. The workflow is useful independently of hosted storage.

For a recorded walkthrough, see the developer guide. For a quick look without registration, open the interactive sample.

Where does your team's accessibility handoff break down: locating the element, reproducing the state, or deciding what has really been verified?

Prepared with AI assistance and checked against the project's CLI documentation and reporting implementation. Automated testing covers only part of accessibility; this is not a completed accessibility assessment.