Custom filename support for Axe reporting (#29)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

<!-- Describe your changes in detail. -->
This adds custom filename support for Axe reporting, so a user can just
specify the name rather than rely on the auto-generated URL value.

## Context

<!-- Why is this change required? What problem does it solve? -->
If someone wants to run the same tests across multiple environments, the
filenames will remain consistent.

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

- [ ] Refactoring (non-breaking change)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [ ] I am familiar with the [contributing
guidelines](../docs/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [x] I have added tests to cover my changes
- [x] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

Author: davethepunkyone

docs/utility-guides/Axe.md

@@ -39,11 +39,12 @@ The `Axe.run(page)` has the following optional arguments that can be passed in:
 
 |Argument|Format|Supported Values|Default Value|Description|
 |--------|------|----------------|-------------|-----------|
-|`ruleset` |list (strings)|Any provided by [axe-core](https://www.deque.com/axe/core-documentation/api-documentation/)|['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'best-practice']|The tags that axe-core uses to filter specific checks. Defaulted to rules used for the WCAG 2.2 AA standard.|
-|`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.|
+|`ruleset` |`list[str]`|Any provided by [axe-core](https://www.deque.com/axe/core-documentation/api-documentation/)|`['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'best-practice']`|The tags that axe-core uses to filter specific checks. Defaulted to rules used for the WCAG 2.2 AA standard.|
+|`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.|
+|`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.|
 
 ## Example usage
 

tests/__init__.py

@@ -1,9 +1,22 @@
 import pytest
+import os
 from pathlib import Path
 from utils.axe import Axe
 
 pytestmark = [pytest.mark.utils]
 
+AXE_REPORTS_DIR = Path(__file__).parent.parent / "axe-reports"
+TEST_JSON_DEFAULT_FILENAME = "www_test_com__1.json"
+TEST_JSON_CUSTOM_FILENAME = "test_json_file.json"
+TEST_HTML_DEFAULT_FILENAME = "www_test_com__1.html"
+TEST_HTML_CUSTOM_FILENAME = "test_html_file.html"
+
+@pytest.fixture(scope="session", autouse=True)
+def remove_files_before_test() -> None:
+    for file in [TEST_JSON_DEFAULT_FILENAME, TEST_JSON_CUSTOM_FILENAME, TEST_HTML_DEFAULT_FILENAME, TEST_HTML_CUSTOM_FILENAME]:
+        if os.path.isfile(AXE_REPORTS_DIR / file):
+            os.remove(AXE_REPORTS_DIR / file)
+
 def test_build_run_command() -> None:
     assert Axe._build_run_command(['test']) == "run({runOnly: { type: 'tag', values: ['test'] }})"
 
@@ -15,9 +28,15 @@ def test_create_path_for_report() -> None:
 
 def test_create_json_report() -> None:
     test_data = {"url": "https://www.test.com/1"}
+
+    # Default generation
     Axe._create_json_report(test_data)
+    with open(AXE_REPORTS_DIR / TEST_JSON_DEFAULT_FILENAME, 'r') as file:
+        assert file.read() == '{"url": "https://www.test.com/1"}'
 
-    with open(Path(__file__).parent.parent / "axe-reports" / "www_test_com__1.json", 'r') as file:
+    # With custom filename
+    Axe._create_json_report(test_data, TEST_JSON_CUSTOM_FILENAME.replace(".json", ""))
+    with open(AXE_REPORTS_DIR / TEST_JSON_CUSTOM_FILENAME, 'r') as file:
         assert file.read() == '{"url": "https://www.test.com/1"}'
 
 def test_create_html_report() -> None:
@@ -34,9 +53,15 @@ def test_create_html_report() -> None:
                 "violations": [{"id": "test", "impact": None, "tags": ["cat.keyboard", "best-practice"], "description": "test", "help": "test", "helpUrl": "test", "nodes": []}]
     }
     expected_file_data = Axe._generate_html(test_data)
+
+    # Default generation
     Axe._create_html_report(test_data)
+    with open(AXE_REPORTS_DIR / TEST_HTML_DEFAULT_FILENAME, 'r') as file:
+        assert file.read() == expected_file_data
 
-    with open(Path(__file__).parent.parent / "axe-reports" / "www_test_com__1.html", 'r') as file:
+    # With custom filename
+    Axe._create_html_report(test_data, TEST_HTML_CUSTOM_FILENAME.replace(".html", ""))
+    with open(AXE_REPORTS_DIR / TEST_HTML_CUSTOM_FILENAME, 'r') as file:
         assert file.read() == expected_file_data
 
 def test_generate_html() -> None:

tests_utils/test_axe.py

@@ -18,6 +18,7 @@ class Axe:
 
     @staticmethod
     def run(page: Page,
+            filename: str = "",
             ruleset: list = ['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'best-practice'],
             report_on_violation_only: bool = False,
             strict_mode: bool = False,
@@ -28,6 +29,7 @@ def run(page: Page,
 
         Args:
             page (playwright.sync_api.Page): The page object to execute axe-core against.
+            filename (str): The filename to use for the outputted reports. If not provided, defaults to the URL under test.
             ruleset (list[str]): [Optional] If provided, a list of strings to denote the ruleset tags axe-core should use. If not provided, defaults to the WCAG 2.2 AA standard (uses tags: 'wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'best-practice').
             report_on_violation_only (bool): [Optional] If true, only generates an Axe report if a violation is detected. If false (default), always generate a report.
             strict_mode (bool): [Optional] If true, raise an exception if a violation is detected. If false (default), proceed with test execution.
@@ -46,9 +48,9 @@ def run(page: Page,
         violations_detected = len(response["violations"]) > 0
         if not report_on_violation_only or (report_on_violation_only and violations_detected):
             if html_report_generated:
-                Axe._create_html_report(response)
+                Axe._create_html_report(response, filename)
             if json_report_generated:
-                Axe._create_json_report(response)
+                Axe._create_json_report(response, filename)
 
         if violations_detected and strict_mode:
             raise AxeAccessibilityException(f"Axe Accessibility Violation detected on page: {response["url"]}")
@@ -77,8 +79,8 @@ def _create_path_for_report(filename: str) -> Path:
         return PATH_FOR_REPORT / filename
 
     @staticmethod
-    def _create_json_report(data: dict) -> Path:
-        filename = f"{Axe._modify_filename_for_report(data["url"])}.json"
+    def _create_json_report(data: dict, filename_overide: str = "") -> None:
+        filename = f"{Axe._modify_filename_for_report(data["url"])}.json" if filename_overide == "" else f"{filename_overide}.json"
         full_path = Axe._create_path_for_report(filename)
 
         with open(full_path, 'w') as file:
@@ -87,8 +89,8 @@ def _create_json_report(data: dict) -> Path:
         logging.info(f"JSON report generated: {full_path}")
 
     @staticmethod
-    def _create_html_report(data: dict) -> None:
-        filename = f"{Axe._modify_filename_for_report(data["url"])}.html"
+    def _create_html_report(data: dict, filename_overide: str = "") -> None:
+        filename = f"{Axe._modify_filename_for_report(data["url"])}.html" if filename_overide == "" else f"{filename_overide}.html"
         full_path = Axe._create_path_for_report(filename)
 
         with open(full_path, 'w') as file: