From a7db9314b48f95d1754191cee9de91128bbbae07 Mon Sep 17 00:00:00 2001 From: jedarden Date: Mon, 6 Jul 2026 00:31:54 -0400 Subject: [PATCH] docs(ci): add accessibility quality gate documentation Add CI accessibility testing guide documenting the WCAG 2.1 AA quality gate that blocks releases on accessibility violations. Update main README to reference the new documentation and clarify that accessibility tests are a CI gate, not just local development tools. This completes the accessibility quality gate requirement. --- README.md | 4 +- docs/ci-accessibility-integration.md | 112 +++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 docs/ci-accessibility-integration.md diff --git a/README.md b/README.md index d564b08..1f56110 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ go build -o spaxel-sim ./cmd/sim # Hardware-free acceptance suite (no ESP32 needed) cd test/acceptance && go test ./... -# Dashboard unit + accessibility tests +# Dashboard unit + accessibility tests (CI quality gate) cd dashboard && npm test && npm run test:a11y ``` @@ -89,6 +89,8 @@ Firmware is built with ESP-IDF 5.2.x — see the *Firmware Build System* section - [`docs/plan/plan.md`](docs/plan/plan.md) — the complete design: architecture, components, schema, deployment, phases - [`docs/notes/`](docs/notes/) — implementation notes (recovery mechanisms, mDNS override, simulation testing, UX) - [`docs/research/`](docs/research/) — CSI fundamentals, physics, algorithms, accuracy limits, prior-art papers +- [`docs/ci-accessibility-integration.md`](docs/ci-accessibility-integration.md) — CI accessibility testing quality gate (WCAG 2.1 AA) +- [`docs/ci-benchmark-integration.md`](docs/ci-benchmark-integration.md) — CI timing benchmark quality gate (fusion loop) - [`dashboard/README.md`](dashboard/README.md) — dashboard test setup (Jest, axe-core + Playwright) - [`PROGRESS.md`](PROGRESS.md) — phase-by-phase implementation status diff --git a/docs/ci-accessibility-integration.md b/docs/ci-accessibility-integration.md new file mode 100644 index 0000000..7fb2882 --- /dev/null +++ b/docs/ci-accessibility-integration.md @@ -0,0 +1,112 @@ +# CI Accessibility Testing Guide + +This document describes the accessibility (a11y) testing integration with Argo Workflows CI. + +## Overview + +Accessibility tests enforce WCAG 2.1 AA compliance as a CI quality gate for the Spaxel dashboard. These tests run automated checks using axe-core and Playwright, ensuring the dashboard remains accessible to users with disabilities. + +**Test location:** `dashboard/tests/a11y*.spec.js` + +**Test runner:** Playwright + @axe-core/playwright + +**What it tests:** WCAG 2.1 AA compliance across: +- Main dashboard pages (index, live, fleet, setup, integrations) +- Onboarding flow +- Dashboard interactive elements + +**Accessibility standard:** WCAG 2.1 AA (via axe-core tags: `wcag2a`, `wcag2aa`) + +## Running Locally + +```bash +# Run accessibility tests +cd dashboard +npm ci +npx playwright install chromium +npm run test:a11y + +# Run specific accessibility test file +npx playwright test a11y.spec.js + +# Run with headed browser (see what's being tested) +npx playwright test a11y.spec.js --headed +``` + +## CI Integration + +The accessibility tests run as a quality gate in the `spaxel-build` Argo WorkflowTemplate. The `a11y-test` step: + +```yaml +- name: a11y-test + template: a11y-test + arguments: + parameters: + - name: version + value: "{{steps.resolve-version.outputs.parameters.version}}" +``` + +**Step details:** +- Runs in parallel with `golangci-lint` (after version resolution) +- Must pass before build proceeds +- Blocks releases on accessibility violations +- No `continueOn.failed` override — failures are hard stops + +## Test Files + +| File | Purpose | +|------|---------| +| `tests/a11y.spec.js` | Main dashboard pages (index, live, fleet, setup, integrations) | +| `tests/a11y-onboarding.spec.js` | New user onboarding flow | +| `tests/a11y-dashboard.spec.js` | Dashboard-specific interactive elements | +| `tests/accessibility/helper.js` | Shared axe-core scanning and assertion helpers | + +## Common Violations + +The axe-core tests catch common accessibility issues: + +- **Color contrast** — text/background contrast ratios < 4.5:1 +- **Missing labels** — form inputs without accessible labels +- **Empty links** — `` tags without descriptive text +- **Heading structure** — skipped heading levels (h1 → h3) +- **ARIA attributes** — missing or incorrect ARIA roles/properties + +## CI Execution + +GitHub Actions are disabled across all repos — all CI runs on Argo Workflows (iad-ci). The accessibility tests are wired into the `spaxel-build` Argo WorkflowTemplate and run automatically on every build. + +**Workflow:** `spaxel-build` +**Namespace:** `argo-workflows` +**Cluster:** `iad-ci` + +## Acceptance Criteria + +The CI gate passes when: +- ✅ All accessibility tests pass (zero violations) +- ✅ No WCAG 2.1 AA violations on any tested page +- ✅ No regressions in previously accessible components + +**Failed gate:** Any accessibility violation blocks the release and must be fixed before deployment. + +## Fixing Violations + +When accessibility tests fail: + +1. **Check the CI logs** — axe-core provides detailed violation reports +2. **Run locally** — reproduce with `npm run test:a11y --headed` +3. **Fix the issue** — update HTML/ARIA attributes in dashboard files +4. **Verify** — re-run tests locally +5. **Commit** — push the fix and re-trigger CI + +## Documentation Updates + +This gate enforces accessibility at the CI level. Complement with: +- Manual testing with screen readers (NVDA, JAWS) +- Keyboard-only navigation testing +- Color-blind accessibility checks + +## Resources + +- [WCAG 2.1 AA Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) +- [axe-core Rules](https://www.deque.com/axe/core-documentation/) +- [Playwright Accessibility Testing](https://playwright.dev/docs/accessibility-testing)