Spaces:

CommunityOne
/

open-navigator

Running on CPU Upgrade

App Files Files Community

open-navigator / web_docs /docs /guides /accessibility-testing.md

jcbowyer

Clean HuggingFace deployment without binary files

e59d91d 22 days ago

preview code

Raw

History Blame Contribute Delete

9.91 kB

metadata

sidebar_position: 12
displayed_sidebar: developersSidebar

Accessibility testing (jurisdiction websites)

Bulk accessibility checks for canonical government homepages in intermediate.int_jurisdiction_websites. Results are stored in Postgres bronze tables for analysis, dashboards, and compliance reporting.

This guide covers how to read these docs, what each engine does, and exact commands to run from the repo root.

How to read this documentation

On the web (local)

From the repo root, start the documentation site:
```
cd website && npm install && npm run start
```
Open the guide in your browser:
- Local dev: http://localhost:3000/docs/guides/accessibility-testing
- If that 404s, try the site home at http://localhost:3000 and use the left nav: Developers & Technical Users → How-To Guides → Accessibility testing.
Production (when deployed): https://www.communityone.com/docs/guides/accessibility-testing

In the repository

Location	Contents
This page (`website/docs/guides/accessibility-testing.md`)	User-facing runbook
`packages/accessibility/src/accessibility/README.md`	Maintainer notes (env vars, file layout)
`packages/accessibility/src/accessibility/.py`, `.mjs`, `*.sh`	Implementations

What gets tested

Layer	Source	Engines	Bronze table
HTML homepages	One URL per `jurisdiction_id` from `int_jurisdiction_websites`	axe-core + Puppeteer, Pa11y-CI	`bronze.bronze_jurisdiction_website_accessibility`
PDF documents	`.pdf` links discovered on those homepages	veraPDF (PDF/UA, PDF/A)	`bronze.bronze_jurisdiction_pdf_verapdf`

HTML tools check WCAG-oriented issues in the DOM. veraPDF checks machine-verifiable PDF/UA and PDF/A rules (industry standard for accessible PDFs).

Prerequisites

Postgres with dbt intermediate built:

./scripts/dbt.sh run --select int_jurisdiction_websites

Python (repo .venv):
```
pip install -r requirements.txt
```
Database URL in .env (first non-empty wins): OPEN_NAVIGATOR_DATABASE_URL, NEON_DATABASE_URL_DEV, or NEON_DATABASE_URL.

HTML scans only — Node 18+:

cd packages/accessibility/src/accessibility && npm install
npx puppeteer browsers install chrome

PDF scans — Docker (recommended; pulls verapdf/cli on first use):

docker --version
docker run --rm verapdf/cli:v1.30.1 -l   # list PDF/UA and PDF/A profiles

Quick start (recommended)

Run everything from the repository root (open-navigator/).

HTML: axe on one state

./packages/accessibility/src/accessibility/run_accessibility_scan.sh --engine axe --state AL

Exports URLs → scans with axe (default concurrency 5) → upserts bronze.bronze_jurisdiction_website_accessibility.

HTML: Pa11y-CI with higher parallelism

PA11YCI_CONCURRENCY=8 WORKER_POOL_SIZE=6 \
  ./packages/accessibility/src/accessibility/run_accessibility_scan.sh --engine pa11y --state AL

PDF: veraPDF on one state

./packages/accessibility/src/accessibility/run_verapdf_scan.sh --state AL --max-pdfs-per-site 3

Discovers PDFs on homepages → validates with PDF/UA profile ua1 by default → upserts bronze.bronze_jurisdiction_pdf_verapdf.

Step-by-step: HTML (axe or Pa11y)

1. Export homepage manifest

One canonical URL per jurisdiction_id (same source priority as jurisdiction discovery):

.venv/bin/python -m accessibility.export_urls --state AL \
  --out data/cache/accessibility/urls-al.json

Sharding for large batches (~20k sites):

.venv/bin/python -m accessibility.export_urls --limit 50 --offset 0 --batch-id shard-0
.venv/bin/python -m accessibility.export_urls --limit 50 --offset 50 --batch-id shard-1

2. Run a scanner

axe-core + Puppeteer:

cd packages/accessibility/src/accessibility
AXE_CONCURRENCY=10 node run_axe_scan.mjs \
  --urls ../../data/cache/accessibility/urls-al.json

Pa11y-CI (worker pool):

cd packages/accessibility/src/accessibility
PA11YCI_CONCURRENCY=8 WORKER_POOL_SIZE=6 WORKER_CHUNK_SIZE=25 \
  node run_pa11y_workers.mjs --urls ../../data/cache/accessibility/urls-al.json

3. Persist to Postgres

.venv/bin/python -m accessibility.persist_results --ensure-ddl \
  --scanner axe --input data/cache/accessibility/axe-<batch-id>.ndjson

.venv/bin/python -m accessibility.persist_results --ensure-ddl \
  --scanner pa11y --input data/cache/accessibility/pa11y-<batch-id>/pa11y-results-merged.json

4. Query HTML results

SELECT jurisdiction_id, website_url, scanner, violation_count, status, scanned_at
FROM bronze.bronze_jurisdiction_website_accessibility
WHERE batch_id = '20260515T120000Z'
ORDER BY violation_count DESC NULLS LAST
LIMIT 50;

DDL (Neon):

psql "$OPEN_NAVIGATOR_DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f packages/hosting/scripts/neon/migrations/032_create_bronze_jurisdiction_website_accessibility.sql

Step-by-step: PDF (veraPDF)

1. Discover PDF links on homepages

.venv/bin/python -m accessibility.export_pdf_urls --state AL \
  --out data/cache/accessibility/pdf-urls-al.json \
  --max-pdfs-per-site 3

Use --from-manifest path.json to skip crawling if you already have a PDF URL list.

2. Download and validate

Default (Docker wraps veraPDF):

.venv/bin/python -m accessibility.run_verapdf_scan \
  --manifest data/cache/accessibility/pdf-urls-al.json

Multiple profiles (e.g. PDF/UA-1 and PDF/UA-2):

VERAPDF_FLAVOURS=ua1,ua2 .venv/bin/python -m accessibility.run_verapdf_scan \
  --manifest data/cache/accessibility/pdf-urls-al.json

Local veraPDF binary (no Docker):

VERAPDF_USE_DOCKER=false VERAPDF_BIN=verapdf \
  .venv/bin/python -m accessibility.run_verapdf_scan \
  --manifest data/cache/accessibility/pdf-urls-al.json

3. Persist PDF results

.venv/bin/python -m accessibility.persist_verapdf_results --ensure-ddl \
  --input data/cache/accessibility/verapdf-<batch-id>.ndjson

4. Query PDF results

SELECT jurisdiction_id, pdf_url, profile_flavour, is_compliant,
       failed_rules, failed_checks, status
FROM bronze.bronze_jurisdiction_pdf_verapdf
WHERE batch_id = '20260515T120000Z'
ORDER BY failed_checks DESC NULLS LAST
LIMIT 50;