Axe Playwright Python

0.1.7 · active · verified Thu Apr 16

Axe Playwright Python facilitates automated web accessibility testing by integrating the axe-core engine with Playwright. It allows developers to scan web pages for accessibility violations within their Playwright test suites. The current version is 0.1.7. Release cadence appears to be irregular, with updates typically occurring every few months based on the project's changelog, often driven by updates to the underlying axe-core JavaScript library.

Common errors

```
ModuleNotFoundError: No module named 'axe_playwright_python'
```
cause The `axe-playwright-python` package was not installed or the import path is incorrect.

fix Run `pip install axe-playwright-python` and ensure the import statement is `from axe_playwright_python.sync_playwright import Axe`.
```
AttributeError: 'Page' object has no attribute 'accessibility'
```
cause Attempting to use Playwright's removed `page.accessibility` API instead of the `axe-playwright-python` integration.

fix Replace calls to `page.accessibility` with `axe.run(page)` after initializing `Axe()` from `axe_playwright_python`.
```
Accessibility issues are present but my test is still passing.
```
cause By default, `axe.run(page)` performs a passive scan and does not automatically fail a test if violations are found. You need to explicitly check the results.

fix After `results = axe.run(page)`, add an assertion to check `results.violations_count`, for example: `assert results.violations_count == 0`.

Warnings

breaking Playwright removed its built-in `page.accessibility` API. Users migrating from older Playwright versions or examples might try to use this deprecated method, leading to `AttributeError` or similar errors.
Fix: Use `axe.run(page)` from `axe-playwright-python` for accessibility scanning.
gotcha Upgrades to the underlying `axe-core` JavaScript engine (which `axe-playwright-python` wraps) can lead to changes in the number, type, or severity of reported accessibility violations. This means test results might differ across `axe-playwright-python` versions even if the application under test remains unchanged.
Fix: Review changelogs for `axe-playwright-python` and `axe-core` when upgrading. Consider using snapshot testing or baseline reporting tools if strict violation counts are critical for your CI/CD.
gotcha While PyPI classifiers for `axe-playwright-python` indicate compatibility with Python >=3.8, the project's explicit dependencies section specifies `Python >= 3.10`. Users on Python 3.8 or 3.9 might encounter unexpected runtime issues or compatibility problems.
Fix: Ensure your Python environment is version 3.10 or higher to guarantee full compatibility.
gotcha Depending on the browser and `axe-core` integration, popup blockers might interfere with `axe.run()` if it attempts to open a new window for analysis. This can lead to the scan failing or hanging.
Fix: Ensure that popup blockers are disabled in the browser context used by Playwright, especially for automated testing environments.

Install

pip install -U axe-playwright-python Install library
playwright install --with-deps Install Playwright browser binaries

Imports

Axe

from axe_playwright_python.sync_playwright import Axe

sync_playwright
```
from playwright.sync_api import sync_playwright
```
Used for setting up Playwright in synchronous tests.

Quickstart

This quickstart demonstrates how to initialize Axe, launch a Playwright browser, navigate to a page, run an accessibility scan, and print the number of violations. It also includes an example of iterating through detected violations.

from playwright.sync_api import sync_playwright
from axe_playwright_python.sync_playwright import Axe

axe = Axe()

with sync_playwright() as playwright:
    browser = playwright.chromium.launch()
    page = browser.new_page()
    page.goto("https://www.google.com")
    results = axe.run(page)
    browser.close()

    print(f"Found {results.violations_count} violations.")
    if results.violations_count > 0:
        print("Accessibility violations found:")
        for violation in results.violations:
            print(f"  - {violation['id']}: {violation['description']} (Impact: {violation['impact']})")
            print(f"    Help: {violation['helpUrl']}")
    else:
        print("No accessibility violations found.")

view raw JSON →