# Pytest Playwright Axe
[](https://github.com/davethepunkyone/pytest-playwright-axe/actions/workflows/build.yaml) [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/pytest-playwright-axe/)
`pytest-playwright-axe` is a package for Playwright Python that allows for the execution of [axe-core](https://github.com/dequelabs/axe-core), a JavaScript
library used for scanning for accessibility issues and providing guidance on how to resolve these issues.
## Table of Contents
- [Pytest Playwright Axe](#pytest-playwright-axe)
- [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Instantiating the Axe class](#instantiating-the-axe-class)
- [Optional arguments](#optional-arguments)
- [.run(): Single page scan](#run-single-page-scan)
- [Required arguments](#required-arguments)
- [Optional arguments](#optional-arguments-1)
- [Returns](#returns)
- [Example usage](#example-usage)
- [.run\_list(): Multiple page scan](#run_list-multiple-page-scan)
- [Required arguments](#required-arguments-1)
- [`page_list dict` Structure](#page_list-dict-structure)
- [Optional arguments](#optional-arguments-2)
- [Returns](#returns-1)
- [Example usage](#example-usage-1)
- [.get\_rules(): Return rules](#get_rules-return-rules)
- [Required Arguments](#required-arguments-2)
- [Optional Arguments](#optional-arguments-3)
- [Returns](#returns-2)
- [Example usage](#example-usage-2)
- [Rulesets](#rulesets)
- [Working With Snapshots](#working-with-snapshots)
- [Example Snapshot Usage](#example-snapshot-usage)
- [Example Reports](#example-reports)
- [Versioning](#versioning)
- [Breaking Changes](#breaking-changes)
- [4.10.3 -\> Onwards](#4103---onwards)
- [Licence](#licence)
- [Acknowledgements](#acknowledgements)
## Prerequisites
This package has the following requirements for use:
- [Python 3.12](https://www.python.org/downloads/) or greater
- [`pytest-playwright`](https://pypi.org/project/pytest-playwright/) 0.5.1 or greater
## Installation
This package is available via PyPi (https://pypi.org/project/pytest-playwright-axe/), so can be installed by running the following
command:
```shell
pip install pytest-playwright-axe
```
## Instantiating the Axe class
You can initialise the Axe class by using the following code in your test file:
```python
from pytest_playwright_axe import Axe
```
You can run the Axe instance either as a standalone instance or instantiate it as follows:
```python
# Standalone execution
Axe().run(page)
# Instantiated execution
axe = Axe()
axe.run(page)
```
### Optional arguments
The `Axe()` class has the following optional arguments that can be passed in:
| Argument | Format | Supported Values | Default Value | Description |
| -------------------- | ----------------------- | ----------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `output_directory` | `pathlib.Path` or `str` | A valid directory path to save results to (e.g. `C:/axe_reports`) | | If provided, sets the directory to save HTML and JSON results into. If not provided (default), the default path is `os.getcwd()/axe-reports`. |
| `css_override` | `str` | A string with valid CSS. | | If provided, this will override the default CSS used in the HTML report with the CSS styling provided. |
| `use_minified_file` | `bool` | `True`, `False` | `False` | If True, use the minified version of axe-core (axe.min.js). If not provided (default), use the full version of axe-core (axe.js). |
| `snapshot_directory` | `pathlib.Path` or `str` | A valid directory path where snapshots are stored (e.g. `C:/snapshots`) | | If provided, sets the directory to check for JSON outputs from previous runs to compare against. |
## .run(): Single page scan
To conduct a scan, you can just use the following once the page you want to check is at the right location:
```python
Axe().run(page)
```
This will inject the axe-core code into the page and then execute the axe.run() command, generating an accessibility report for the page being tested.
By default, the `Axe().run(page)` command will do the following:
- Scan the page passed in with the default axe-core configuration
- Generate a HTML and JSON report with the findings in the `axe-reports` directory, regardless of if any violations are found
- Any steps after the `Axe().run()` command will continue to execute, and it will not cause the test in progress to fail (it runs a passive scan of the page)
- Will return the full response from axe-core as a dict object if the call is set to a variable, e.g. `axe_results = Axe().run(page)` will populate `axe_results` to interact with as required
This uses the [axe-core run method outlined in the axe-core documentation](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axerun).
### Required arguments
The following are required for `Axe().run()`:
| Argument | Format | Description |
| -------- | ------------------------ | -------------------------------------------- |
| page | playwright.sync_api.Page | A Playwright Page on the page to be checked. |
### Optional arguments
The `Axe().run(page)` has the following optional arguments that can be passed in:
| Argument | Format | Supported Values | Default Value | Description |
| -------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename` | `str` | A string valid for a filename (e.g. `test_report`) | | If provided, HTML and JSON reports will save with the filename provided. If not provided (default), the URL of the page under test will be used as the filename. |
| `context` | `str` | A JavaScript object, represented as a string (e.g. `{ exclude: '.ad-banner' }`) | | If provided, adds the [context that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#context-parameter). |
| `options` | `str` | A JavaScript object, represented as a string (e.g. `{ runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } }`) | | If provided, adds the [options that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#options-parameter). |
| `report_on_violation_only` | `bool` | `True`, `False` | `False` | If True, HTML and JSON reports will only be generated if at least one violation is found. |
| `strict_mode` | `bool` | `True`, `False` | `False` | If True, when a violation is found an AxeAccessibilityException is raised, causing a test failure. |
| `html_report_generated` | `bool` | `True`, `False` | `True` | If True, a HTML report will be generated summarising the axe-core findings. |
| `json_report_generated` | `bool` | `True`, `False` | `True` | If True, a JSON report will be generated with the full axe-core findings. |
### Returns
This function can be used independently, but when set to a variable returns a `dict` with the axe-core results.
### Example usage
A default execution with no arguments:
```python
from pytest_playwright_axe import Axe
from playwright.sync_api import Page
def test_axe_example(page: Page) -> None:
page.goto("https://github.com/davethepunkyone/pytest-playwright-axe")
Axe().run(page)
```
A WCAG 2.2 (AA) execution, with a custom filename, strict mode enabled and only HTML output provided:
```python
from pytest_playwright_axe import Axe
from playwright.sync_api import Page
def test_axe_example(page: Page) -> None:
page.goto("https://github.com/davethepunkyone/pytest-playwright-axe")
Axe().run(page,
filename="test_report",
options="{runOnly: {type: 'tag', values: ['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22a', 'wcag22aa', 'best-practice']}}",
strict_mode=True,
json_report_generated=False)
```
## .run_list(): Multiple page scan
To scan multiple URLs within your application, you can use the following method:
```python
Axe().run_list(page, page_list)
```
This runs the `Axe().run(page)` function noted above against each URL provided in the `page_list` argument, and will generate reports as required. This navigates by using the Playwright Page's `.goto()` method, so this only works for pages that can be directly accessed.
### Required arguments
The following are required for `Axe().run_list()`:
| Argument | Format | Description |
| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | `playwright.sync_api.Page` | A Playwright Page object to drive navigation to each page to test. |
| page_list | `list[` `str` or `dict` `]` | A list of URLs to execute against (e.g. `["home", "profile", "product/test"]`). If a dict is provided, basic actions and assertions can be conducted as part of the list prior to the scan being conducted. |
> NOTE: It is heavily recommended that when using the `run_list` command, that you set a `--base-url` either via the pytest.ini file or by passing in the value when using the `pytest` command in the command line. By doing this, the list you pass in will not need to contain the base URL value and therefore make any scanning transferrable between environments.
#### `page_list dict` Structure
The `page_list` supports providing a list made up of `str` format urls (that will just navigate to the page and scan) and providing
a `dict`, whereby a basic action can be provided along with a basic assertion (to prove the action completed successfully) before the
scan is undertaken.
If a dict is provided as part of the `page_list`, the following key / value pairs can be provided:
| Key | Required | Format | Allowed Values | Description |
| ---------------- | --------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `url` | Yes | `str` | | The url to initially navigate to. |
| `action` | Yes | `str` | `click`, `dblclick`, `hover`, `fill`, `type`, `select_option` | The action to undertake to get to the desired page state. |
| `locator` | Yes | `playwright.sync_api.Locator` | | The locator to perform the action against. |
| `value` | No (Yes if action is one of: `fill`, `type`, `select_option`) | `str` | | The value to use for the action, when a value is required. |
| `assert_type` | No (Yes if assertion required) | `str` | `to_be_visible`, `to_be_hidden`, `to_be_enabled`, `to_contain_text`, `to_not_contain_text` | If conducting an assertion, the type of assertion to complete. |
| `assert_locator` | No (Yes if assertion required) | `playwright.sync_api.Locator` | | The locator to perform the assertion against. |
| `assert_value` | No (Yes if assert_type is one of: `to_contain_text`, `to_not_contain_text`) | `str` | | The value to use for the assertion, when a value is required. |
| `wait_time` | No | `int` | | If provided, the amount of time to wait after completing the defined action and assertion in milliseconds before running Axe. |
> NOTE: This format has been provided to allow for basic actions to be completed whilst using the `run_list()` method if checking
> multiple pages in succession, but is not designed to replace comprehensive testing. If you need to do anything more complex than
> a single basic action, it is recommended that you write a test that does the actions first and then use the `run()` method instead.
### Optional arguments
The `Axe().run_list(page, page_list)` function has the following optional arguments that can be passed in:
| Argument | Format | Supported Values | Default Value | Description |
| -------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `use_list_for_filename` | `bool` | `True`, `False` | `True` | If True, the filename will be derived from the value provided in the list. If False, the full URL will be used. |
| `context` | `str` | A JavaScript object, represented as a string (e.g. `{ exclude: '.ad-banner' }`) | | If provided, adds the [context that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#context-parameter). |
| `options` | `str` | A JavaScript object, represented as a string (e.g. `{ runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } }`) | | If provided, adds the [options that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#options-parameter). |
| `report_on_violation_only` | `bool` | `True`, `False` | `False` | If True, HTML and JSON reports will only be generated if at least one violation is found. |
| `strict_mode` | `bool` | `True`, `False` | `False` | If True, when a violation is found an AxeAccessibilityException is raised, causing a test failure. |
| `html_report_generated` | `bool` | `True`, `False` | `True` | If True, a HTML report will be generated summarising the axe-core findings. |
| `json_report_generated` | `bool` | `True`, `False` | `True` | If True, a JSON report will be generated with the full axe-core findings. |
### Returns
This function can be used independently, but when set to a variable returns a `dict` with the axe-core results for all pages scanned (using the URL value in the list provided as the key).
### Example usage
When using the following command: `pytest --base-url https://www.github.com`:
```python
from pytest_playwright_axe import Axe
from playwright.sync_api import Page
def test_accessibility(page: Page) -> None:
# A list of URLs to loop through
urls_to_check = [
"davethepunkyone/pytest-playwright-axe",
"davethepunkyone/pytest-playwright-axe/issues",
{
"url": "https://github.com/davethepunkyone/pytest-playwright-axe",
"action": "click",
"locator": page.get_by_test_id("anchor-button"),
"assert_type": "to_contain_text",
"assert_locator": page.get_by_test_id("overlay-content"),
"assert_value": "rework-axe-to-include-init",
"wait_time": 1000
}
]
Axe().run_list(page, urls_to_check)
```
## .get_rules(): Return rules
You can get the rules used for specific tags by using this method, or all rules if no ruleset is provided.
This uses the [axe-core getRules method outlined in the axe-core documentation](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axegetrules).
### Required Arguments
The following are required for `Axe().get_rules()`:
| Argument | Format | Description |
| -------- | -------------------------- | -------------------------------------------------------- |
| page | `playwright.sync_api.Page` | A Playwright Page object.. This page can be empty/blank. |
### Optional Arguments
The `Axe().get_rules(page, page_list)` function has the following optional arguments that can be passed in:
| Argument | Format | Supported Values | Default Value | Description |
| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| `rules` | `list[str]` | A Python list with strings representing [valid tags](https://www.deque.com/axe/core-documentation/api-documentation/#axecore-tags). | `None` | If provided, the list of rules to provide information on. If not provided, return details for all rules. |
### Returns
A Python `list[dict]` object with all matching rules and their descriptors.
### Example usage
```python
import logging
from pytest_playwright_axe import Axe
from playwright.sync_api import Page
def test_get_rules(page: Page) -> None:
rules = Axe().get_rules(page, ['wcag21aa'])
for rule in rules:
logging.info(rule)
```
## Rulesets
The following rulesets can also be imported via the `pytest_playwright_axe` module:
| Ruleset | Import | Rules Applied |
| ----------- | ------------------- | -------------------------------------------------------------------------------------- |
| WCAG 2.2 AA | `OPTIONS_WCAG_22AA` | `['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22a', 'wcag22aa', 'best-practice']` |
Example:
```python
from pytest_playwright_axe import Axe, OPTIONS_WCAG_22AA
from playwright.sync_api import Page
def test_axe_example(page: Page) -> None:
page.goto("https://github.com/davethepunkyone/pytest-playwright-axe")
Axe().run(page, options=OPTIONS_WCAG_22AA)
```
## Working With Snapshots
From release 4.11.0.post1, this package provides the ability to compare to a
previous scan of the page and highlight changes between then and now.
Scans are conducted against the JSON output of a previous run, so to use this
functionality you will need to ensure you save JSON files as part of your outputs.
If any changes are detected and snapshot scanning is enabled, a new section will
be populated at the start of the HTML report that outlines the detected changes, as
shown in the screenshot below.
When working with snapshots, the following needs to be considered:
- Snapshots are detected from the designated snapshot directory based on the expected filename, so to use this logic the URLs under test will need to be consistent.
- The comparison output is only presented on the HTML version of the report.
### Example Snapshot Usage
**1 - Get Initial Snapshot**
An initial scan of the page is conducted, with JSON output enabled.
For the purposes of this example, the following test is located in the
`tests/accessibility` directory in `tests_accessibility.py`:
```python
from playwright.sync_api import Page
from pytest_playwright_axe import Axe
def test_axe_example(page: Page) -> None:
page.goto("https://github.com/davethepunkyone/pytest-playwright-axe")
Axe().run(page)
```
This generates the following output in the `axe-reports` directory:
axe-reports/
|- github_com_davethepunkyone_pytest-playwright-axe.html
|- github_com_davethepunkyone_pytest-playwright-axe.json
The `.json` file should then be copied into an appropriate directory to be
referenced later (e.g. `tests/accessibility/snapshots`).
This should then result in a file structure like so:
axe-reports/
|- github_com_davethepunkyone_pytest-playwright-axe.html
|- github_com_davethepunkyone_pytest-playwright-axe.json
tests/
|- accessibility/
| |- snapshots/
| | |- github_com_davethepunkyone_pytest-playwright-axe.json
| |- tests_accessibility.py
**2 - Compare Snapshots**
To allow for the snapshot comparison, the test needs to be amended to check
for available snapshots, by adding the `snapshot_directory=<path>` to the
initialised Axe instance.
Using our example above, we would modify the existing test as follows:
```python
from playwright.sync_api import Page
from pytest_playwright_axe import Axe
from pathlib import Path
# Reference the snapshot directory
SNAPSHOT_DIRECTORY = Path(__file__).parent.joinpath("snapshots")
def test_axe_example(page: Page) -> None:
page.goto("https://github.com/davethepunkyone/pytest-playwright-axe")
# Initialise Axe referencing the snapshot directory
Axe(snapshot_directory=SNAPSHOT_DIRECTORY).run(page)
```
With this change in place, the test will now check the `snapshots` directory
and as this will generate a JSON file matching the one we have added, it will
load the JSON file from `snapshots/github_com_davethepunkyone_pytest-playwright-axe.json`
and check for changes between the two files, outputting the results in a new
section on the HTML report.
## Example Reports
The following are examples of the reports generated using this package:
| Format | Example |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| HTML (Use download file to see report) | [Example File](https://github.com/davethepunkyone/pytest-playwright-axe/tree/main/examples/example_result_report.html) |
| JSON | [Example File](https://github.com/davethepunkyone/pytest-playwright-axe/tree/main/examples/example_result_report.json) |
## Versioning
The versioning for this project is designed to be directly linked to the releases from
the [axe-core](https://github.com/dequelabs/axe-core) project, to accurately reflect the
version of axe-core that is being executed.
## Breaking Changes
The following section outlines important breaking changes between version, due to the
versioning of this project being aligned with axe-core.
### 4.10.3 -> Onwards
The following significant changes have been applied for releases after 4.10.3, which
would require amending existing logic:
- The `Axe()` module logic is no longer static, so using `Axe.run()` will no longer work.
- `output_directory` has now been moved into the `__init__` method for `Axe`, and is no longer defined in the `.run()` and `run_list()` functions.
## Licence
Unless stated otherwise, the codebase is released under the
[MIT Licence](LICENCE.md) (note the UK spelling for the filename).
This covers both the codebase and any sample code in the documentation.
## Acknowledgements
This package was created based on work initially designed for the
[NHS England Playwright Python Blueprint](https://github.com/nhs-england-tools/playwright-python-blueprint).
Raw data
{
"_id": null,
"home_page": null,
"name": "pytest-playwright-axe",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "accessibility, playwright, axe, axe-core, pytest, wcag, testing",
"author": null,
"author_email": "Dave Harding <dave@punkamania.org>",
"download_url": "https://files.pythonhosted.org/packages/7b/77/d54e02ec300c80b4fb1cc9efee1c26938a97328ef5fd75eda7e8de0a8dc1/pytest_playwright_axe-4.11.0.post1.tar.gz",
"platform": null,
"description": "# Pytest Playwright Axe\n\n[](https://github.com/davethepunkyone/pytest-playwright-axe/actions/workflows/build.yaml) [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/pytest-playwright-axe/)\n\n`pytest-playwright-axe` is a package for Playwright Python that allows for the execution of [axe-core](https://github.com/dequelabs/axe-core), a JavaScript\nlibrary used for scanning for accessibility issues and providing guidance on how to resolve these issues.\n\n## Table of Contents\n\n- [Pytest Playwright Axe](#pytest-playwright-axe)\n - [Table of Contents](#table-of-contents)\n - [Prerequisites](#prerequisites)\n - [Installation](#installation)\n - [Instantiating the Axe class](#instantiating-the-axe-class)\n - [Optional arguments](#optional-arguments)\n - [.run(): Single page scan](#run-single-page-scan)\n - [Required arguments](#required-arguments)\n - [Optional arguments](#optional-arguments-1)\n - [Returns](#returns)\n - [Example usage](#example-usage)\n - [.run\\_list(): Multiple page scan](#run_list-multiple-page-scan)\n - [Required arguments](#required-arguments-1)\n - [`page_list dict` Structure](#page_list-dict-structure)\n - [Optional arguments](#optional-arguments-2)\n - [Returns](#returns-1)\n - [Example usage](#example-usage-1)\n - [.get\\_rules(): Return rules](#get_rules-return-rules)\n - [Required Arguments](#required-arguments-2)\n - [Optional Arguments](#optional-arguments-3)\n - [Returns](#returns-2)\n - [Example usage](#example-usage-2)\n - [Rulesets](#rulesets)\n - [Working With Snapshots](#working-with-snapshots)\n - [Example Snapshot Usage](#example-snapshot-usage)\n - [Example Reports](#example-reports)\n - [Versioning](#versioning)\n - [Breaking Changes](#breaking-changes)\n - [4.10.3 -\\> Onwards](#4103---onwards)\n - [Licence](#licence)\n - [Acknowledgements](#acknowledgements)\n\n## Prerequisites\n\nThis package has the following requirements for use:\n\n- [Python 3.12](https://www.python.org/downloads/) or greater\n- [`pytest-playwright`](https://pypi.org/project/pytest-playwright/) 0.5.1 or greater\n\n## Installation\n\nThis package is available via PyPi (https://pypi.org/project/pytest-playwright-axe/), so can be installed by running the following\ncommand:\n\n```shell\npip install pytest-playwright-axe\n```\n\n## Instantiating the Axe class\n\nYou can initialise the Axe class by using the following code in your test file:\n\n```python\nfrom pytest_playwright_axe import Axe\n```\n\nYou can run the Axe instance either as a standalone instance or instantiate it as follows:\n\n```python\n# Standalone execution\nAxe().run(page)\n\n# Instantiated execution\naxe = Axe()\naxe.run(page)\n```\n\n### Optional arguments\n\nThe `Axe()` class has the following optional arguments that can be passed in:\n\n| Argument | Format | Supported Values | Default Value | Description |\n| -------------------- | ----------------------- | ----------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `output_directory` | `pathlib.Path` or `str` | A valid directory path to save results to (e.g. `C:/axe_reports`) | | If provided, sets the directory to save HTML and JSON results into. If not provided (default), the default path is `os.getcwd()/axe-reports`. |\n| `css_override` | `str` | A string with valid CSS. | | If provided, this will override the default CSS used in the HTML report with the CSS styling provided. |\n| `use_minified_file` | `bool` | `True`, `False` | `False` | If True, use the minified version of axe-core (axe.min.js). If not provided (default), use the full version of axe-core (axe.js). |\n| `snapshot_directory` | `pathlib.Path` or `str` | A valid directory path where snapshots are stored (e.g. `C:/snapshots`) | | If provided, sets the directory to check for JSON outputs from previous runs to compare against. |\n\n\n## .run(): Single page scan\n\nTo conduct a scan, you can just use the following once the page you want to check is at the right location:\n\n```python\nAxe().run(page)\n```\n\nThis will inject the axe-core code into the page and then execute the axe.run() command, generating an accessibility report for the page being tested.\n\nBy default, the `Axe().run(page)` command will do the following:\n\n- Scan the page passed in with the default axe-core configuration\n- Generate a HTML and JSON report with the findings in the `axe-reports` directory, regardless of if any violations are found\n- Any steps after the `Axe().run()` command will continue to execute, and it will not cause the test in progress to fail (it runs a passive scan of the page)\n- Will return the full response from axe-core as a dict object if the call is set to a variable, e.g. `axe_results = Axe().run(page)` will populate `axe_results` to interact with as required\n\nThis uses the [axe-core run method outlined in the axe-core documentation](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axerun).\n\n### Required arguments\n\nThe following are required for `Axe().run()`:\n\n| Argument | Format | Description |\n| -------- | ------------------------ | -------------------------------------------- |\n| page | playwright.sync_api.Page | A Playwright Page on the page to be checked. |\n\n### Optional arguments\n\nThe `Axe().run(page)` has the following optional arguments that can be passed in:\n\n| Argument | Format | Supported Values | Default Value | Description |\n| -------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `filename` | `str` | A string valid for a filename (e.g. `test_report`) | | If provided, HTML and JSON reports will save with the filename provided. If not provided (default), the URL of the page under test will be used as the filename. |\n| `context` | `str` | A JavaScript object, represented as a string (e.g. `{ exclude: '.ad-banner' }`) | | If provided, adds the [context that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#context-parameter). |\n| `options` | `str` | A JavaScript object, represented as a string (e.g. `{ runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } }`) | | If provided, adds the [options that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#options-parameter). |\n| `report_on_violation_only` | `bool` | `True`, `False` | `False` | If True, HTML and JSON reports will only be generated if at least one violation is found. |\n| `strict_mode` | `bool` | `True`, `False` | `False` | If True, when a violation is found an AxeAccessibilityException is raised, causing a test failure. |\n| `html_report_generated` | `bool` | `True`, `False` | `True` | If True, a HTML report will be generated summarising the axe-core findings. |\n| `json_report_generated` | `bool` | `True`, `False` | `True` | If True, a JSON report will be generated with the full axe-core findings. |\n\n### Returns\n\nThis function can be used independently, but when set to a variable returns a `dict` with the axe-core results.\n\n### Example usage\n\nA default execution with no arguments:\n\n```python\nfrom pytest_playwright_axe import Axe\nfrom playwright.sync_api import Page\n\ndef test_axe_example(page: Page) -> None:\n page.goto(\"https://github.com/davethepunkyone/pytest-playwright-axe\")\n Axe().run(page)\n```\n\nA WCAG 2.2 (AA) execution, with a custom filename, strict mode enabled and only HTML output provided:\n\n```python\nfrom pytest_playwright_axe import Axe\nfrom playwright.sync_api import Page\n\ndef test_axe_example(page: Page) -> None:\n page.goto(\"https://github.com/davethepunkyone/pytest-playwright-axe\")\n Axe().run(page, \n filename=\"test_report\",\n options=\"{runOnly: {type: 'tag', values: ['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22a', 'wcag22aa', 'best-practice']}}\",\n strict_mode=True,\n json_report_generated=False)\n```\n\n## .run_list(): Multiple page scan\n\nTo scan multiple URLs within your application, you can use the following method:\n\n```python\nAxe().run_list(page, page_list)\n```\n\nThis runs the `Axe().run(page)` function noted above against each URL provided in the `page_list` argument, and will generate reports as required. This navigates by using the Playwright Page's `.goto()` method, so this only works for pages that can be directly accessed.\n\n### Required arguments\n\nThe following are required for `Axe().run_list()`:\n\n| Argument | Format | Description |\n| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| page | `playwright.sync_api.Page` | A Playwright Page object to drive navigation to each page to test. |\n| page_list | `list[` `str` or `dict` `]` | A list of URLs to execute against (e.g. `[\"home\", \"profile\", \"product/test\"]`). If a dict is provided, basic actions and assertions can be conducted as part of the list prior to the scan being conducted. |\n\n> NOTE: It is heavily recommended that when using the `run_list` command, that you set a `--base-url` either via the pytest.ini file or by passing in the value when using the `pytest` command in the command line. By doing this, the list you pass in will not need to contain the base URL value and therefore make any scanning transferrable between environments.\n\n#### `page_list dict` Structure\n\nThe `page_list` supports providing a list made up of `str` format urls (that will just navigate to the page and scan) and providing\na `dict`, whereby a basic action can be provided along with a basic assertion (to prove the action completed successfully) before the\nscan is undertaken.\n\nIf a dict is provided as part of the `page_list`, the following key / value pairs can be provided:\n\n| Key | Required | Format | Allowed Values | Description |\n| ---------------- | --------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |\n| `url` | Yes | `str` | | The url to initially navigate to. |\n| `action` | Yes | `str` | `click`, `dblclick`, `hover`, `fill`, `type`, `select_option` | The action to undertake to get to the desired page state. |\n| `locator` | Yes | `playwright.sync_api.Locator` | | The locator to perform the action against. |\n| `value` | No (Yes if action is one of: `fill`, `type`, `select_option`) | `str` | | The value to use for the action, when a value is required. |\n| `assert_type` | No (Yes if assertion required) | `str` | `to_be_visible`, `to_be_hidden`, `to_be_enabled`, `to_contain_text`, `to_not_contain_text` | If conducting an assertion, the type of assertion to complete. |\n| `assert_locator` | No (Yes if assertion required) | `playwright.sync_api.Locator` | | The locator to perform the assertion against. |\n| `assert_value` | No (Yes if assert_type is one of: `to_contain_text`, `to_not_contain_text`) | `str` | | The value to use for the assertion, when a value is required. |\n| `wait_time` | No | `int` | | If provided, the amount of time to wait after completing the defined action and assertion in milliseconds before running Axe. |\n\n> NOTE: This format has been provided to allow for basic actions to be completed whilst using the `run_list()` method if checking\n> multiple pages in succession, but is not designed to replace comprehensive testing. If you need to do anything more complex than\n> a single basic action, it is recommended that you write a test that does the actions first and then use the `run()` method instead.\n\n### Optional arguments\n\nThe `Axe().run_list(page, page_list)` function has the following optional arguments that can be passed in:\n\n| Argument | Format | Supported Values | Default Value | Description |\n| -------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `use_list_for_filename` | `bool` | `True`, `False` | `True` | If True, the filename will be derived from the value provided in the list. If False, the full URL will be used. |\n| `context` | `str` | A JavaScript object, represented as a string (e.g. `{ exclude: '.ad-banner' }`) | | If provided, adds the [context that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#context-parameter). |\n| `options` | `str` | A JavaScript object, represented as a string (e.g. `{ runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } }`) | | If provided, adds the [options that axe-core should use](https://www.deque.com/axe/core-documentation/api-documentation/?_gl=1*nt1pxm*_up*MQ..*_ga*Mjc3MzY4NDQ5LjE3NDMxMDMyMDc.*_ga_C9H6VN9QY1*MTc0MzEwMzIwNi4xLjAuMTc0MzEwMzIwNi4wLjAuODE0MjQyMzA2#options-parameter). |\n| `report_on_violation_only` | `bool` | `True`, `False` | `False` | If True, HTML and JSON reports will only be generated if at least one violation is found. |\n| `strict_mode` | `bool` | `True`, `False` | `False` | If True, when a violation is found an AxeAccessibilityException is raised, causing a test failure. |\n| `html_report_generated` | `bool` | `True`, `False` | `True` | If True, a HTML report will be generated summarising the axe-core findings. |\n| `json_report_generated` | `bool` | `True`, `False` | `True` | If True, a JSON report will be generated with the full axe-core findings. |\n\n### Returns\n\nThis function can be used independently, but when set to a variable returns a `dict` with the axe-core results for all pages scanned (using the URL value in the list provided as the key).\n\n### Example usage\n\nWhen using the following command: `pytest --base-url https://www.github.com`:\n\n```python\nfrom pytest_playwright_axe import Axe\nfrom playwright.sync_api import Page\n\ndef test_accessibility(page: Page) -> None:\n # A list of URLs to loop through\n urls_to_check = [\n \"davethepunkyone/pytest-playwright-axe\",\n \"davethepunkyone/pytest-playwright-axe/issues\",\n {\n \"url\": \"https://github.com/davethepunkyone/pytest-playwright-axe\",\n \"action\": \"click\", \n \"locator\": page.get_by_test_id(\"anchor-button\"), \n \"assert_type\": \"to_contain_text\", \n \"assert_locator\": page.get_by_test_id(\"overlay-content\"),\n \"assert_value\": \"rework-axe-to-include-init\",\n \"wait_time\": 1000\n }\n ]\n\n Axe().run_list(page, urls_to_check)\n```\n\n## .get_rules(): Return rules\n\nYou can get the rules used for specific tags by using this method, or all rules if no ruleset is provided.\n\nThis uses the [axe-core getRules method outlined in the axe-core documentation](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axegetrules).\n\n### Required Arguments\n\nThe following are required for `Axe().get_rules()`:\n\n| Argument | Format | Description |\n| -------- | -------------------------- | -------------------------------------------------------- |\n| page | `playwright.sync_api.Page` | A Playwright Page object.. This page can be empty/blank. |\n\n### Optional Arguments\n\nThe `Axe().get_rules(page, page_list)` function has the following optional arguments that can be passed in:\n\n| Argument | Format | Supported Values | Default Value | Description |\n| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------- |\n| `rules` | `list[str]` | A Python list with strings representing [valid tags](https://www.deque.com/axe/core-documentation/api-documentation/#axecore-tags). | `None` | If provided, the list of rules to provide information on. If not provided, return details for all rules. |\n\n### Returns\n\nA Python `list[dict]` object with all matching rules and their descriptors.\n\n### Example usage\n\n```python\nimport logging\nfrom pytest_playwright_axe import Axe\nfrom playwright.sync_api import Page\n\ndef test_get_rules(page: Page) -> None:\n\n rules = Axe().get_rules(page, ['wcag21aa'])\n for rule in rules:\n logging.info(rule)\n```\n\n## Rulesets\n\nThe following rulesets can also be imported via the `pytest_playwright_axe` module:\n\n| Ruleset | Import | Rules Applied |\n| ----------- | ------------------- | -------------------------------------------------------------------------------------- |\n| WCAG 2.2 AA | `OPTIONS_WCAG_22AA` | `['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22a', 'wcag22aa', 'best-practice']` |\n\nExample:\n\n```python\nfrom pytest_playwright_axe import Axe, OPTIONS_WCAG_22AA\nfrom playwright.sync_api import Page\n\ndef test_axe_example(page: Page) -> None:\n page.goto(\"https://github.com/davethepunkyone/pytest-playwright-axe\")\n Axe().run(page, options=OPTIONS_WCAG_22AA)\n```\n\n## Working With Snapshots\n\nFrom release 4.11.0.post1, this package provides the ability to compare to a\nprevious scan of the page and highlight changes between then and now.\nScans are conducted against the JSON output of a previous run, so to use this\nfunctionality you will need to ensure you save JSON files as part of your outputs.\n\nIf any changes are detected and snapshot scanning is enabled, a new section will\nbe populated at the start of the HTML report that outlines the detected changes, as\nshown in the screenshot below.\n\n\n\nWhen working with snapshots, the following needs to be considered:\n\n- Snapshots are detected from the designated snapshot directory based on the expected filename, so to use this logic the URLs under test will need to be consistent.\n- The comparison output is only presented on the HTML version of the report.\n\n### Example Snapshot Usage\n\n**1 - Get Initial Snapshot**\n\nAn initial scan of the page is conducted, with JSON output enabled.\n\nFor the purposes of this example, the following test is located in the\n`tests/accessibility` directory in `tests_accessibility.py`:\n\n```python\nfrom playwright.sync_api import Page\nfrom pytest_playwright_axe import Axe\n\ndef test_axe_example(page: Page) -> None:\n page.goto(\"https://github.com/davethepunkyone/pytest-playwright-axe\")\n Axe().run(page)\n```\n\nThis generates the following output in the `axe-reports` directory:\n\n axe-reports/\n |- github_com_davethepunkyone_pytest-playwright-axe.html\n |- github_com_davethepunkyone_pytest-playwright-axe.json\n\nThe `.json` file should then be copied into an appropriate directory to be\nreferenced later (e.g. `tests/accessibility/snapshots`).\n\nThis should then result in a file structure like so:\n\n axe-reports/\n |- github_com_davethepunkyone_pytest-playwright-axe.html\n |- github_com_davethepunkyone_pytest-playwright-axe.json\n tests/\n |- accessibility/\n | |- snapshots/\n | | |- github_com_davethepunkyone_pytest-playwright-axe.json\n | |- tests_accessibility.py\n\n**2 - Compare Snapshots**\n\nTo allow for the snapshot comparison, the test needs to be amended to check\nfor available snapshots, by adding the `snapshot_directory=<path>` to the\ninitialised Axe instance.\n\nUsing our example above, we would modify the existing test as follows:\n\n```python\nfrom playwright.sync_api import Page\nfrom pytest_playwright_axe import Axe\nfrom pathlib import Path\n\n# Reference the snapshot directory\nSNAPSHOT_DIRECTORY = Path(__file__).parent.joinpath(\"snapshots\")\n\ndef test_axe_example(page: Page) -> None:\n page.goto(\"https://github.com/davethepunkyone/pytest-playwright-axe\")\n # Initialise Axe referencing the snapshot directory\n Axe(snapshot_directory=SNAPSHOT_DIRECTORY).run(page)\n```\n\nWith this change in place, the test will now check the `snapshots` directory\nand as this will generate a JSON file matching the one we have added, it will\nload the JSON file from `snapshots/github_com_davethepunkyone_pytest-playwright-axe.json`\nand check for changes between the two files, outputting the results in a new\nsection on the HTML report.\n\n\n## Example Reports\n\nThe following are examples of the reports generated using this package:\n\n| Format | Example |\n| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| HTML (Use download file to see report) | [Example File](https://github.com/davethepunkyone/pytest-playwright-axe/tree/main/examples/example_result_report.html) |\n| JSON | [Example File](https://github.com/davethepunkyone/pytest-playwright-axe/tree/main/examples/example_result_report.json) |\n\n## Versioning\n\nThe versioning for this project is designed to be directly linked to the releases from \nthe [axe-core](https://github.com/dequelabs/axe-core) project, to accurately reflect the\nversion of axe-core that is being executed.\n\n## Breaking Changes\n\nThe following section outlines important breaking changes between version, due to the\nversioning of this project being aligned with axe-core.\n\n### 4.10.3 -> Onwards\n\nThe following significant changes have been applied for releases after 4.10.3, which\nwould require amending existing logic:\n\n- The `Axe()` module logic is no longer static, so using `Axe.run()` will no longer work.\n- `output_directory` has now been moved into the `__init__` method for `Axe`, and is no longer defined in the `.run()` and `run_list()` functions.\n\n## Licence\n\nUnless stated otherwise, the codebase is released under the\n[MIT Licence](LICENCE.md) (note the UK spelling for the filename).\nThis covers both the codebase and any sample code in the documentation.\n\n## Acknowledgements\n\nThis package was created based on work initially designed for the \n[NHS England Playwright Python Blueprint](https://github.com/nhs-england-tools/playwright-python-blueprint).\n",
"bugtrack_url": null,
"license": null,
"summary": "An axe-core integration for accessibility testing using Playwright Python.",
"version": "4.11.0.post1",
"project_urls": {
"Homepage": "https://github.com/davethepunkyone/pytest-playwright-axe",
"Issues": "https://github.com/davethepunkyone/pytest-playwright-axe/issues",
"Repository": "https://github.com/davethepunkyone/pytest-playwright-axe"
},
"split_keywords": [
"accessibility",
" playwright",
" axe",
" axe-core",
" pytest",
" wcag",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5da6d64829830dcc1583226426b231529836caf932780c8d7d4927258aa3228d",
"md5": "f41c0a165b12183f7702ed392c8140b0",
"sha256": "8f4a041c2ca034a665ac0fb383827552ea23744e9c9546c90b23adddf06808bf"
},
"downloads": -1,
"filename": "pytest_playwright_axe-4.11.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f41c0a165b12183f7702ed392c8140b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 398527,
"upload_time": "2025-11-01T17:00:35",
"upload_time_iso_8601": "2025-11-01T17:00:35.915618Z",
"url": "https://files.pythonhosted.org/packages/5d/a6/d64829830dcc1583226426b231529836caf932780c8d7d4927258aa3228d/pytest_playwright_axe-4.11.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7b77d54e02ec300c80b4fb1cc9efee1c26938a97328ef5fd75eda7e8de0a8dc1",
"md5": "db815630af184b38bb0656494e4606be",
"sha256": "840c7c965cddfbc28d809f4dcf22aeb89b5d90b3cfd033f04077e6ff88797162"
},
"downloads": -1,
"filename": "pytest_playwright_axe-4.11.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "db815630af184b38bb0656494e4606be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 789022,
"upload_time": "2025-11-01T17:00:37",
"upload_time_iso_8601": "2025-11-01T17:00:37.240082Z",
"url": "https://files.pythonhosted.org/packages/7b/77/d54e02ec300c80b4fb1cc9efee1c26938a97328ef5fd75eda7e8de0a8dc1/pytest_playwright_axe-4.11.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 17:00:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davethepunkyone",
"github_project": "pytest-playwright-axe",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest-playwright",
"specs": [
[
">=",
"0.5.1"
]
]
}
],
"lcname": "pytest-playwright-axe"
}
JSON
