Skip to content

Accessibility browser extension

Build, connect, test, and debug the local-first axe-core extension for voiqq Accessibility projects.

What version 1 does

  • Runs the current packaged axe-core release inside the user's own browser tab
  • Adds normalized HTML-based observations to an existing or new Accessibility project
  • Preserves normal voiqq bug IDs, team permissions, assignments, fields, history, reports, and VPAT mappings
  • Refreshes automated evidence when URL, rule ID, and selector identify an existing observation

Build and load locally

  1. Run npm install from the voiqq repository
  2. Run npm run extension:build
  3. Open chrome://extensions or edge://extensions
  4. Enable Developer mode and select Load unpacked
  5. Choose extensions/voiqq-axe/dist
  6. Start local voiqq, sign in, and open Projects in the same browser profile

Connect securely

Open the extension popup and select Connect on voiqq, or use Connect in the Auto-populate dialog. The signed-in page creates a one-use two-minute ticket. The extension exchanges it for an opaque, revocable 24-hour token. Supabase cookies, access tokens, service-role credentials, and passwords never enter extension storage.

Run an Accessibility scan

  1. Open Projects and select Auto-populate
  2. Choose Existing Project or New Project
  3. Paste one HTTP or HTTPS URL per line, or upload a CSV URL list; voiqq accepts up to 5,000 unique pages and persists them in 50-page batches
  4. Select Start Scan
  5. Keep voiqq open while the extension scans each page sequentially
  6. Review the resulting Open findings with Pending validation

Data and duplicate handling

voiqq stores the page URL and title, axe rule and description, impact, help URL, selector, HTML snippet, failure summary, tags, WCAG references, scan time, browser version, and axe version. It does not capture screenshots, recordings, visual diffs, or raw axe result trees.

The server recomputes a fingerprint from canonical URL, rule ID, and selector. A new fingerprint creates a normal finding. A repeated fingerprint refreshes only automated evidence and never overwrites the auditor's edits, comments, assignments, validation, or manual evidence.

Test the integration

  • Run npm run test:automated-scans
  • Run npm run extension:check
  • Run npm run extension:build
  • Run npm run check and npm run build
  • Scan a known violation, edit the resulting finding, scan again, and confirm no duplicate appears and the manual edit remains
  • Append a second URL to the same project and confirm new findings use the existing bug ID flow

Debug locally

  • Use the service worker Inspect link on chrome://extensions
  • Check the popup and Auto-populate dialog for persisted progress
  • Reload the unpacked extension after every source rebuild
  • Reconnect when the extension belongs to another local voiqq account
  • A restricted URL or page timeout is recorded as a page error while the remaining queue continues
voiqq Accessibility browser extension