jedarden a7db9314b4 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.

2026-07-06 00:32:03 -04:00

3.7 KiB

Raw Blame History

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

# 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:

- 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 — <a> 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:

Check the CI logs — axe-core provides detailed violation reports
Run locally — reproduce with npm run test:a11y --headed
Fix the issue — update HTML/ARIA attributes in dashboard files
Verify — re-run tests locally
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

3.7 KiB Raw Blame History