axe-selenium-python

Common errors

• WebDriverException: Message: 'chromedriver' executable needs to be in PATH.

  cause Selenium cannot find the executable for the Chrome browser driver because it's not in the system's PATH.
  fix Download `chromedriver` from `chromedriver.chromium.org` and place the executable in a directory that is included in your system's PATH environment variable. Alternatively, specify the `executable_path` when initializing the Chrome driver: `webdriver.Chrome(executable_path='/path/to/chromedriver')`.

• Getting empty results even though there are violations on the page

  cause Axe-core might not be able to detect violations for elements that are hidden or not fully rendered when `axe.inject()` or `axe.run()` is called. This can also happen if the `context` or `options` parameters are too restrictive.
  fix Ensure that the elements you wish to test are visible and fully loaded on the page before calling `axe.inject()` and `axe.run()`. Use Selenium's explicit waits (`WebDriverWait`) to ensure elements are present and visible. Review the `context` and `options` passed to `axe.run()` to ensure they are not inadvertently excluding relevant parts of the page.

• AttributeError: 'Axe' object has no attribute 'execute'

  cause Attempting to call the `execute` method on the `Axe` object, which was renamed to `run`.
  fix Update your code to use `axe.run()` instead of `axe.execute()`.

Warnings

• breaking The `Axe` class method `execute` was renamed to `run` in version 2.1.5 (or a direct pre-cursor to 2.1.6) to align with the axe-core API. Code using `axe.execute()` will fail.
  Fix: Replace calls to `axe.execute()` with `axe.run()`.
• gotcha The `axe-selenium-python` package on PyPI, specifically version 2.1.6, is considered to be in maintenance mode, with its last significant update in 2018. For active development, newer Python/Selenium compatibility, and up-to-date axe-core integration (e.g., axe-core@4.x), consider using community-maintained forks like `django-commons/axe-selenium-python` which is more current (e.g., version 3.0+).
  Fix: For new projects or if encountering compatibility issues with modern Python/Selenium, evaluate using `pip install django-commons-axe-selenium-python` (check the exact package name as forks might vary) and adjust imports if necessary (e.g., `from django_commons_axe_selenium_python import Axe`). Always refer to the latest fork's documentation.
• gotcha Some functionalities, such as specific helper methods and advanced reporting, were moved to a separate package `pytest-axe` starting from version 2.0.0. If you rely on these features, you will need to install and use `pytest-axe` in conjunction with `axe-selenium-python`.
  Fix: Install `pytest-axe` (`pip install pytest-axe`) and consult its documentation for moved functionalities.
• gotcha The `axe-selenium-python` library requires a compatible browser WebDriver (e.g., Chromedriver for Chrome, Geckodriver for Firefox) to be installed on your system and available in your system's PATH environment variable. Failure to do so will result in Selenium not being able to launch the browser.
  Fix: Download the appropriate WebDriver for your browser and operating system (e.g., from `chromedriver.chromium.org` or `github.com/mozilla/geckodriver/releases`), place the executable in a directory, and add that directory to your system's PATH.

Install

• pip install axe-selenium-python Install latest 2.x version

Imports

• Axe

  from axe_selenium_python import Axe

• webdriver

  from selenium import webdriver

  Standard Selenium import, not part of axe-selenium-python directly.

Quickstart

This quickstart demonstrates how to initialize a Selenium WebDriver, inject the axe-core script using `Axe().inject()`, run accessibility checks with `Axe().run()`, and optionally save the results to a JSON file and report violations. It's crucial to have a compatible browser driver (like geckodriver or chromedriver) installed and accessible in your system's PATH.

import os
from selenium import webdriver
from axe_selenium_python import Axe

# Configure a browser (e.g., Firefox or Chrome)
# Ensure the appropriate WebDriver (e.g., geckodriver, chromedriver) is in your PATH
# For Chrome, you might need: driver = webdriver.Chrome()
driver = webdriver.Firefox()

try:
    driver.get("http://www.google.com")

    axe = Axe(driver)

    # Inject axe-core javascript into the page
    axe.inject()

    # Run axe accessibility checks
    results = axe.run()

    # Write results to a JSON file
    output_dir = "a11y_reports"
    os.makedirs(output_dir, exist_ok=True)
    axe.write_results(results, os.path.join(output_dir, 'google_a11y.json'))

    # Assert no violations are found (optional)
    if len(results["violations"]) > 0:
        print("Accessibility Violations Found:")
        print(axe.report(results["violations"]))
        # assert False, "Accessibility violations found!"
    else:
        print("No accessibility violations found.")

finally:
    driver.quit()