wcag-pdf-pytest

wcag-pdf-pytest is a pytest plugin that scaffolds WCAG 2.1 compliance testing for PDF documents. The plugin auto-generates one test per WCAG 2.1 Success Criterion (SC) that applies to PDFs, organizes them by conformance level, and exposes CLI switches for narrowing execution to the criteria relevant to your review.

Features

• SC-aware test generation — each applicable WCAG 2.1 SC ships as an individual pytest module with structured docstrings that document the requirement.
• Level-based selection — mark sets (A, AA, AAA) and CLI flags allow you to focus on the conformance tier under audit.
• Context-aware filtering — opt-in inclusion of "Depends" criteria lets you decide when to execute context-sensitive checks.
• Extensible PDF inspection — centralize heavy lifting in pdf_inspector.py so new assertions or document parsers can be layered in without touching the generated tests.

Installation

pip

pip install wcag-pdf-pytest[pdf]

uv

uv add wcag-pdf-pytest[pdf]

Install the optional pdf extra when you need the bundled pypdf helpers.

Usage

Run the full WCAG 2.1 test suite against a PDF document:

pytest --wcag-pdf path/to/file.pdf

Execute only Level AA criteria using pytest markers:

pytest -m "AA" --wcag-pdf path/to/file.pdf

The plugin also exposes explicit CLI options:

pytest --wcag-pdf-level AA --wcag-pdf path/to/file.pdf
pytest --wcag-pdf-include-depends --wcag-pdf path/to/file.pdf

Tests are namespaced under the wcag21 marker to keep discovery isolated from other pytest plugins. Each test is seeded with an xfail placeholder so you can progressively replace the stub assertion with a concrete PDF accessibility check.

CLI reference

Combine CLI switches with pytest marker expressions for granular selection during CI runs.

Extending PDF checks

Extend wcag_pdf_pytest/pdf_inspector.py with reusable utilities that evaluate individual criteria. Generated tests should stay declarative — import helpers from the inspector module to keep assertions maintainable and consistent across the suite.

License

Apache License 2.0. See LICENSE for details.