axe-devtools-api Python API Reference
API reference for the axe-devtools-api Python package for injecting and running axe-core
Provides an API with which to inject and run axe-core against a web page.
axe_devtools_api.Axe
Configures how axe-core is run and runs it against the page.
report = Axe(page).with_rules("document-title", "label").analyze()Axe(page, report_configuration=None, axe_source=None)
Initialize an Axe instance with a browser adapter and optional configuration.
page: A browser adapter, such as an AxeDriver instance from axe-devtools-selenium.
report_configuration: Optional. A report configuration object.
axe_source: Optional. A string of axe-core source code to use instead of the bundled version.
analyze()
Inject axe-core into the page and run the accessibility analysis.
Returns a Results object. See Generating Reports With Python for the full Results API and how to configure report metadata.
report = Axe(page).analyze()including(*selector)
Specify part of the page for axe-core to analyze. To analyze several unrelated parts of the page, call including() once for each one, passing a single selector each time.
selector: A single CSS selector for the elements to include. Passing more than one selector in a single call is always interpreted as an iframe selector rather than as separate includes: every selector but the last matches one level of iframe nesting, and the last matches the element to analyze inside the innermost iframe.
Returns this object for chaining.
# Analyze .sidebar and .some-class, which are both in the top-level document
report = Axe(page).including(".sidebar").including(".some-class").analyze()
# Analyze .some-class inside the iframe matched by .sidebar-frame
report = Axe(page).including(".sidebar-frame", ".some-class").analyze()excluding(*selector)
Specify part of the page for axe-core to skip during analysis. To skip several unrelated parts of the page, call excluding() once for each one, passing a single selector each time.
selector: A single CSS selector for the elements to exclude. Passing more than one selector in a single call is always interpreted as an iframe selector rather than as separate exclusions: every selector but the last matches one level of iframe nesting, and the last matches the element to skip inside the innermost iframe.
Returns this object for chaining.
# Skip .third-party-ad and .cookie-banner, which are both in the top-level document
report = Axe(page).excluding(".third-party-ad").excluding(".cookie-banner").analyze()
# Skip .third-party-ad inside the iframe matched by .iframe1
report = Axe(page).excluding(".iframe1", ".third-party-ad").analyze()with_rules(*rules)
Specify rules (by ID) for axe-core to run. Only the specified rules are used. This option is incompatible with with_tags.
rules: One or more rule IDs. See Rule Descriptions for a list of valid IDs.
Returns this object for chaining.
Raises RuntimeError if called together with with_tags on the same instance.
report = Axe(page).with_rules("document-title", "label").analyze()with_tags(*tags)
Specify rules (by tag) for axe-core to run. Only the specified rules are used. This option is incompatible with with_rules.
tags: One or more tag names. See axe-core tags for a list of valid tags.
Returns this object for chaining.
Raises RuntimeError if called together with with_rules on the same instance.
report = Axe(page).with_tags("best-practice", "wcag2a").analyze()disabling_rules(*rules)
Disable specific rules from the axe-core run.
rules: One or more rule IDs.
Returns this object for chaining.
report = Axe(page).disabling_rules("html-has-lang", "label").analyze()run_options(options)
Specify runOptions to pass to axe-core when calling axe.run.
options: Options object to pass to axe-core.
Returns this object for chaining.
options = {"iframes": False}
report = Axe(page).run_options(options).analyze()configure(spec)
Configure axe-core via axe.configure.
spec: Spec object to pass to axe.configure.
Returns this object for chaining.
report = Axe(page).configure(spec).analyze()without_iframe_sandboxes()
Remove the sandbox attribute from iframes so that axe-core can run inside them.
Returns this object for chaining.
report = Axe(page).without_iframe_sandboxes().analyze()with_config_file(config_path)
Set the path to a ruleset config file. The default path is config/axe-ruleset.json, or the value of the $AXE_RULESET_PATH environment variable if set.
config_path: Path to the config file.
Returns this object for chaining.
report = Axe(page).with_config_file("path/to/file.json").analyze()with_ruleset(ruleset_id, enable_best_practices=False)
Use a specific ruleset for the axe-core run.
ruleset_id: ID of the ruleset to use. Available rulesets: wcag2, wcag2.1, wcag2.2, wcag2aaa, wcag2.1aaa, wcag2.2aaa, 508, en301549, ttv5, rgaav4.
enable_best_practices: Whether to enable rules tagged best-practice. Defaults to False.
Returns this object for chaining.
report = Axe(page).with_ruleset("508").analyze()set_legacy_mode(state=True)
Use axe.run instead of axe.runPartial. Has cross-origin implications.
state: Whether to enable legacy mode. Defaults to True.
Returns this object for chaining.
report = Axe(page).set_legacy_mode().analyze()Usage Service
Gain insight into Axe DevTools usage trends within your organization. By default the usage service is enabled and reports to https://usage.deque.com. Set the AXE_TRACK_USAGE environment variable to false to disable it.
Usage service environment variables
These environment variables allow you to configure the usage service and change the properties of reported events.
| Name | Type | Can Override | Description |
|---|---|---|---|
AXE_DISTINCT_ID |
String | — | A UUID identifier that remains the same for the logged-in user (unless it is regenerated). In Ruby, this variable is named DEQUE_DISTINCT_ID. |
AXE_INCLUDE_TEST_RESULTS |
Boolean | — | Set to true to include the full axe-core results in the testResults object of each event (default is false). Supported by the CLI and the Node.js APIs only. |
AXE_METRICS_URL |
String | — | The URL of the REST usage endpoint (default is https://usage.deque.com) |
AXE_TRACK_USAGE |
Boolean | — | Set to false to disable usage service reporting. Reporting is enabled by default. |
AXE_APPLICATION |
String | false | The application that was used to check for accessibility errors |
AXE_DEV_INSTANCE |
Boolean | true | Indicates whether this event is from a software developer's actions. Useful for marking and later removing events logged during development or testing. |
AXE_DEPARTMENT |
String | true | The user's department within the organization |
AXE_KEYCLOAK_ID |
String | false | The user's Keycloak ID |
AXE_LOGGED_IN |
Boolean | false | Records whether the user is logged in to the application under test |
AXE_ORGANIZATION |
String | true | The user's organization. To have your usage appear in Axe Reports, set this to your organization's ID (contact Deque to obtain it). |
AXE_SESSION_ID |
String | false | A UUID identifying the user's session |
AXE_USER_ID |
String | false | A specific user's identity such as an email address, name, or login ID. Axe Reports counts unique users from this value. |
AXE_USER_JOB_ROLE |
String | false | The user's job role |
AXE_USER_STATUS |
String | false | Status information you want to associate with the user |
enable_tracking(state)
Opt in or out of sending data to the usage service. Sending is enabled by default.
state: Whether tracking is enabled.
Returns this object for chaining.
report = Axe(page).enable_tracking(True).analyze()set_tracking_url(url)
Set where usage metrics data are sent.
url: URL where data will be sent.
Returns this object for chaining.
report = Axe(page).set_tracking_url("https://usage.deque.com").analyze()set_distinct_id(id)
Set the distinct ID used when sending usage metrics.
id: Distinct ID to send.
Returns this object for chaining.
report = Axe(page).set_distinct_id("SOMEUUID").analyze()