A command-line tool for automated detection of common Section 508 / WCAG accessibility barriers in web content — 14 checks across static HTML and JavaScript-rendered pages, with console, JSON, and Markdown reports.
The Section 508 Compliance Checker CLI is the first project in my Section 508 SME and Compliance Analyst portfolio. It automates the detection of common accessibility issues in HTML content so that audits move faster and remediation starts sooner.
The tool inspects rendered pages for the kinds of defects that map directly to the Revised Section 508 Standards — which incorporate WCAG 2.0 Level A and AA success criteria by reference. Because many current federal procurements and agency policies now call for WCAG 2.1 Level AA, checks are mapped to WCAG 2.1 as well (2.1 is backward-compatible with 2.0), and each finding produces a structured, human-readable report an analyst can act on.
Scope note: Automated tooling can reliably flag a subset of accessibility failures (roughly 30–40% of WCAG success criteria). It is a force multiplier for a human evaluator, not a replacement for manual testing with assistive technology. This tool is built to surface high-signal, machine-detectable issues and to document what still requires manual review.
- Automated page analysis — loads a live URL or local HTML file and scans the rendered DOM.
- Checks mapped to Section 508 / WCAG success criteria, including:
- Missing or empty
alttext on images (WCAG 1.1.1) - Form inputs without associated labels (WCAG 1.3.1, 4.1.2)
- Missing document
langattribute (WCAG 3.1.1) - Missing or non-descriptive page
<title>(WCAG 2.4.2) - Improper heading structure / skipped heading levels (WCAG 1.3.1, 2.4.6)
- Links with no discernible text (WCAG 2.4.4)
- Tables missing header associations (WCAG 1.3.1)
iframeelements without atitle(WCAG 4.1.2)- Insufficient text/background color contrast (WCAG 1.4.3) — full-page under
--render selenium, inline styles otherwise; see the note under Roadmap - Low-contrast form-field boundaries and meaningful graphics/icons
(WCAG 1.4.11 Non-text Contrast) — full-page under
--render selenium - Missing keyboard focus indicator (WCAG 2.4.7) — tested via real keyboard
tabbing under
--render selenium - Missing or duplicate main landmark (WCAG 1.3.1)
- Duplicate banner / contentinfo landmarks (WCAG 1.3.1)
- Multiple navigation landmarks without accessible names (WCAG 1.3.1)
- Missing skip link when navigation is present (WCAG 2.4.1)
- Missing or empty
- Two rendering backends:
- BeautifulSoup for fast static-HTML parsing
- Selenium for JavaScript-rendered pages and dynamic content
- Structured reporting — results grouped by severity with the mapped success criterion, element location, and remediation guidance.
- Multiple output formats — console, JSON, and Markdown for inclusion in audit deliverables.
- CI-friendly exit codes — non-zero exit on violations for use in build pipelines.
| Component | Purpose |
|---|---|
| Python 3.10+ | Core language |
| Selenium | Browser automation for JS-rendered pages |
| BeautifulSoup | HTML parsing for static content |
| Pillow | Pixel-sampling page screenshots to resolve backgrounds |
| argparse | Command-line interface |
Requires Python 3.10+.
# Clone the repository
git clone https://github.com/AngComply/section-508-compliance-checker-cli.git
cd section-508-compliance-checker-cli
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtThe --render selenium backend drives headless Chrome/Chromium, which must
be installed on the host. The matching driver is resolved automatically by
Selenium Manager
(bundled with Selenium 4.6+), so no separate chromedriver install is required.
The static backend (the default) needs no browser at all.
To run the test suite, install the development dependencies instead:
pip install -r requirements-dev.txt
pytest# Scan a live URL (static parsing)
python checker.py --url https://example.gov
# Scan a JavaScript-rendered page (Selenium backend)
python checker.py --url https://example.gov --render selenium
# Scan a local HTML file
python checker.py --file ./page.html
# Emit a JSON report to a file
python checker.py --url https://example.gov --format json --output report.json
# Emit a Markdown report for an audit deliverable
python checker.py --url https://example.gov --format markdown --output findings.md| Flag | Description |
|---|---|
--url <url> |
Target URL to scan |
--file <path> |
Local HTML file to scan |
--render {static,selenium} |
Rendering backend (default: static) |
--format {console,json,markdown} |
Report format (default: console) |
--output <path> |
Write the report to a file instead of stdout |
--fail-on {error,any,none} |
Exit non-zero when issues are found — error (default) fails on errors, any on any finding, none never fails (CI use) |
--timeout <seconds> |
Network timeout for URL fetches (default: 30) |
Section 508 Compliance Report — https://example.gov
============================================================
[ERROR] 1.1.1 Non-text Content
Image is missing an alt attribute.
<img src="/logo.png"/>
→ Add descriptive alt text, or alt="" if the image is purely decorative.
[WARNING] 2.4.2 Page Titled
The page title 'Home' is generic and non-descriptive.
<title>
→ Use a specific title that distinguishes this page from others.
------------------------------------------------------------
Summary: 1 error, 1 warning, 6 of 8 checks passed
Each finding is tied to a specific WCAG success criterion referenced by the Revised Section 508 Standards, so results drop directly into an Accessibility Conformance Report (ACR / VPAT) workflow. The tool is designed to complement — not replace — manual evaluation with screen readers (JAWS, NVDA, VoiceOver), keyboard-only navigation, and color-contrast analysis.
- Core checker engine (
checker.py) and check modules -
requirements.txtand pinned dependencies - BeautifulSoup static backend
- Selenium dynamic backend
- JSON and Markdown reporters
- Unit tests and sample fixtures
- CI workflow (GitHub Actions: ruff lint + pytest matrix)
- Color-contrast analysis (WCAG 1.4.3) — full-page (Selenium computed styles) and inline (static)
- Landmark checks — main, banner/contentinfo uniqueness, navigation naming, skip link (WCAG 1.3.1 / 2.4.1)
- Non-text contrast for form fields and meaningful graphics/icons, plus keyboard focus visibility (WCAG 1.4.11 / 2.4.7)
- Pixel-sampling of the rendered screenshot to resolve backgrounds painted
by gradients, images,
::beforepseudo-elements, or overlays outside the text's ancestor chain (Selenium) - PDF, mobile, and ARIA widget-pattern checks (future scope)
Sixteen checks ship today, mapped to WCAG 1.1.1, 1.3.1, 1.4.3, 1.4.11, 2.4.1,
2.4.2, 2.4.4, 2.4.7, 3.1.1, and 4.1.2. See the source in
section508checker/checks/.
Color-contrast scope: With
--render selenium, the check reads each text element's real rendered color and background viagetComputedStyle, so it evaluates the full page regardless of where the styles come from (inline, embedded, external, or inherited). Semi-transparent background layers are composited down to the first opaque color. When the background can't be resolved from the DOM — e.g. text over a CSS gradient, background image,::beforepseudo-element, or an overlay outside the ancestor chain — the tool samples the actual rendered pixels from a page screenshot to recover the real background color. That measures what's painted rather than guessing, so it stays free of false positives; elements that still can't be resolved are skipped. Without a browser (static / file input), only inlinestyleattributes are visible, so an element is assessed only when both its foreground and an opaque background are determinable inline. For the most complete results, run with--render selenium.
This tool is part of a broader portfolio demonstrating hands-on Section 508 testing and remediation capability. See docs/Portfolio.md for the full portfolio overview.
Automated results are advisory. A conformance determination requires manual testing by a qualified evaluator. This tool does not certify Section 508 compliance.
Released under the MIT License.