Merge remote-tracking branch 'origin' into feature/BCSS-20606-new-regression-release-seek-further-data

# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.
#
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.

Author: Andyg79

.gitleaksignore

@@ -221,3 +221,9 @@ cd9c0efec38c5d63053dd865e5d4e207c0760d91:docs/guides/Perform_static_analysis.md:
 751ddbd178e91293c20282df62e8d3fe1086310a:utils/resources/axe.js:ipv4:32080
 751ddbd178e91293c20282df62e8d3fe1086310a:utils/resources/axe.js:ipv4:32089
 751ddbd178e91293c20282df62e8d3fe1086310a:utils/resources/axe.js:ipv4:32103
+cae84544e2852202f5d0abb9ad18f9d83a0c6d80:subject_criteria_builder/criteria.json:generic-api-key:4210
+203cd8811be75d33859eb7c7cc8a48beb5a2b8b2:subject_criteria_builder/criteria.json:generic-api-key:4210
+60468a7d6f3ff3259616757be85d6f07e62d00b6:subject_criteria_builder/criteria.json:generic-api-key:4210
+145171b9e9d169acb136fc527708c997c9ad9f61:subject_criteria_builder/criteria.json:generic-api-key:4210
+2ccb5e91033934d4818c1efa2eb1696b5511ebc9:subject_criteria_builder/criteria.json:generic-api-key:4210
+145171b9e9d169acb136fc527708c997c9ad9f61:subject_criteria_builder/criteria.json:generic-api-key:4210

Makefile

@@ -5,4 +5,22 @@ include scripts/init.mk
 
 # ==============================================================================
 
-# NOTE: This project currently only uses this Makefile as part of CI/CD checks.
+# This allows the setup of Playwright by using a single command ready to use, and checks
+# if the user is in a virtual environment before running the setup.
+
+.PHONY: check-venv
+check-venv: # Checks if in a Python venv / VIRTUALENV before installing a bunch of dependencies
+	@python -c "import sys, os; \
+venv = (hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix) or 'VIRTUAL_ENV' in os.environ); \
+import sys; sys.exit(0 if venv else 1)"
+
+setup-playwright: # Install Playwright and associated packages, and create local.env
+	@echo "Checking for virtual environment..."
+	$(MAKE) check-venv || (echo "ERROR: Not in a virtual environment, please create before running this command!"; exit 1)
+
+	@echo "Install Playwright"
+	pip install -r requirements.txt
+	playwright install
+
+	@echo "Setup local.env file"
+	python setup_env_file.py

README.md

@@ -1,6 +1,6 @@
 # BCSS Playwright Test Suite
 
-[![CI/CD Pull Request](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/playwright-python-blueprint/actions/workflows/cicd-1-pull-request.yaml)
+[![CI/CD Pull Request](https://github.com/nhs-england-tools/playwright-python-blueprint/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/playwright-python-blueprint/actions/workflows/cicd-1-pull-request.yaml)
 
 This repository contains the automated UI test suite for the BCSS application, built using [Playwright Python](https://playwright.dev/python/). It provides a structured framework and reusable utilities to support consistent, maintainable test development across the project.
 
@@ -48,7 +48,8 @@ Note: This project is actively maintained and evolving.
       - [3. Best Practices](#3-best-practices)
       - [4. Blueprint Utilities](#4-blueprint-utilities)
       - [5. BCSS Project Specific Utilities](#5-bcss-project-specific-utilities)
-    - [Contributing](#contributing)
+  - [Using the Jira Upload Script](#using-the-jira-upload-script)
+  - [Contributing](#contributing)
     - [Contacts](#contacts)
     - [Licence](#licence)
 
@@ -379,7 +380,57 @@ These utilities have been created specifically for the bcss playwright project:
 | [Table Utility](.docs/utility-guides/TableUtil.md)                                      | Provides helper methods for interacting with HTML tables, including row selection, column indexing, and data extraction.                       |
 | [User Tools](.docs/utility-guides/UserTools.md)                                         | Manages test user credentials via `users.json`, supports login automation, and retrieves user metadata for role-based testing.                 |
 
-### Contributing
+## Using the Jira Upload Script
+
+Included with this code is a Jira Upload utility that will allow for the uploading of artifacts from test runs to
+a Jira ticket directly. The script itself ([`jira_upload.py`](jira_upload.py)) can be invoked using the following
+command:
+
+```shell
+python jira_upload.py
+```
+
+For this to work, you need to set the follow environment variables (which you can do via local.env):
+
+| Key                   | Required | Description                                                                                            |
+| --------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `JIRA_URL`              | Yes      | The Jira instance url to connect to                                                                    |
+| `JIRA_PROJECT_KEY`      | Yes      | The project key for the Jira project to upload to                                                      |
+| `JIRA_API_KEY`          | Yes      | The Jira API key for your user, which can be generated in Jira via Profile > Personal Access Tokens    |
+| `JIRA_TICKET_REFERENCE` | No       | The Jira ticket you want to default to, if required. Can be left blank to use branch-based referencing |
+
+This command will do the following actions:
+
+1. Work out the Jira ticket to upload to and confirm it is a valid reference, by using the following logic:
+   1. If a `--jira-ref` value has been provided, use that value.
+   2. If a `JIRA_TICKET_REFERENCE` environment variable exists, use that value.
+   3. If none of the above, check if you are in a feature branch and if so, compiles the Jira ticket reference by combining the project key and the end of the feature branch (when in the format `feature/<shortcode>-<jira_ticket_number>`).
+2. Check the `test-results/` directory (or custom directory if specified) for appropriate files under 10MB (Jira's file limit), specifically:
+   1. HTML files (e.g. `report.html` generated by `pytest`).
+   2. Trace Files (e.g. `test_name/trace.zip` generated by Playwright).
+   3. Screenshots (e.g. `test_screenshot.png` generated by Playwright).
+   4. CSV Files (e.g. `results.csv` generated during test execution from the UI).
+3. Prompt the user to confirm that they are updating the correct ticket and the correct files are being uploaded. If files already exist on the ticket with a matching name, a unique name will be provided unless `--overwrite-files` is provided.
+4. If `y` is selected, upload the files and add a comment (unless `--no-comment` is provided) to Jira outlining the files uploaded and if possible, the environment information from the test run (unless `--no-env-data` is provided).
+
+You can also pass in the following arguments which will have the noted effects:
+
+| Argument                      | Description                                                                                                                   |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `--jira-ref <Jira Reference>` | The Jira ticket to upload to. Will take precedence over auto-deriving from branch name and the set environment variable.      |
+| `--results-dir <Directory>`   | The directory to point to. If not set, points to `test-results/` (the default directory for test results in this repository). |
+| `--no-html`                   | Don't include HTML files in the upload.                                                                                       |
+| `--no-trace`                  | Don't include Trace files (.zip) in the upload.                                                                               |
+| `--no-csv`                    | Don't include CSV files in the upload.                                                                                        |
+| `--no-screenshots`            | Don't include screenshots (.png) in the upload.                                                                               |
+| `--no-comment`                | Don't add a Jira comment highlighting the results.                                                                            |
+| `--no-env-data`               | Don't include environment data in the Jira comment (if getting environment data has been configured).                         |
+| `--overwrite-files`           | If a filename exists on the ticket that matches those in the results directory, overwrite them.                               |
+| `--auto-confirm`              | Will not ask if you want to proceed if provided, and will assume that yes has been pressed.                                   |
+
+Further information on the available actions for this logic can be found in the [Jira Confluence Utility utility guide](./docs/utility-guides/JiraConfluenceUtil.md).
+
+## Contributing
 
 Further guidance on contributing to this project can be found in our [contribution](./CONTRIBUTING.md) page.
 

classes/address/address.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Address:
+    """
+    Represents a postal address with up to five address lines and a postcode.
+    Provides methods to format the address as a string.
+    """
+
+    address_line1: str = ""
+    address_line2: str = ""
+    address_line3: str = ""
+    address_line4: str = ""
+    address_line5: str = ""
+    post_code: str = ""
+
+    def set_address_line(self, line_number: int, address_line: str) -> None:
+        """
+        Sets the specified address line (1-5) to the given value.
+
+        Args:
+            line_number (int): The address line number (1-5).
+            address_line (str): The value to set for the address line.
+
+        Raises:
+            ValueError: If line_number is not between 1 and 5.
+        """
+        if not 1 <= line_number <= 5:
+            raise ValueError(
+                f"Invalid line number {line_number}, must be between 1 and 5"
+            )
+
+        setattr(self, f"address_line{line_number}", address_line)
+
+    def __str__(self) -> str:
+        """
+        Returns the formatted address as a single string.
+        """
+        address_parts = [
+            self.address_line1,
+            self.address_line2,
+            self.address_line3,
+            self.address_line4,
+            self.address_line5,
+            self.post_code,
+        ]
+        return ", ".join([part for part in address_parts if part])

classes/address_contact_type.py classes/address/address_contact_type.pyclasses/address_contact_type.py renamed to classes/address/address_contact_type.py

@@ -0,0 +1,67 @@
+from enum import Enum
+from typing import Optional
+
+
+class AppointmentSlotType(Enum):
+    """
+    Enum representing appointment slot types, mapped to valid value IDs and descriptions.
+    Provides utility methods for lookup by description (case-sensitive and insensitive) and by valid value ID.
+    """
+
+    COLONOSCOPY_ASSESSMENT = (209028, "Colonoscopy Assessment")
+    BOWEL_SCOPE_AUTOMATIC = (200526, "FS Automatic")
+    BOWEL_SCOPE_MANUAL = (200527, "FS Manual")
+    POSITIVE_ASSESSMENT = (6016, "Positive Assessment")
+    POST_INVESTIGATION = (6017, "Post-Investigation")
+    SURVEILLANCE = (20061, "Surveillance")
+
+    def __init__(self, valid_value_id: int, description: str) -> None:
+        self._valid_value_id = valid_value_id
+        self._description = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the valid value ID for the appointment slot type.
+        """
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """
+        Returns the description for the appointment slot type.
+        """
+        return self._description
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["AppointmentSlotType"]:
+        """
+        Returns the enum member matching the given description (case-sensitive).
+        """
+        for member in cls:
+            if member.description == description:
+                return member
+        return None
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["AppointmentSlotType"]:
+        """
+        Returns the enum member matching the given description (case-insensitive).
+        """
+        desc_lower = description.lower()
+        for member in cls:
+            if member.description.lower() == desc_lower:
+                return member
+        return None
+
+    @classmethod
+    def by_valid_value_id(cls, valid_value_id: int) -> Optional["AppointmentSlotType"]:
+        """
+        Returns the enum member matching the given valid value ID.
+        """
+        for member in cls:
+            if member.valid_value_id == valid_value_id:
+                return member
+        return None

classes/address_type.py classes/address/address_type.pyclasses/address_type.py renamed to classes/address/address_type.py

@@ -0,0 +1,66 @@
+from enum import Enum
+from typing import Optional
+
+
+class AppointmentStatusType(Enum):
+    """
+    Enum representing appointment status types, mapped to valid value IDs and descriptions.
+    """
+
+    ATTENDED = (6121, "Attended")
+    BOOKED = (6120, "Booked")
+    CANCELLED = (6122, "Cancelled")
+    DID_NOT_ATTEND = (6123, "Did Not Attend")
+
+    def __init__(self, valid_value_id: int, description: str) -> None:
+        self._valid_value_id = valid_value_id
+        self._description = description
+
+    @property
+    def valid_value_id(self) -> int:
+        """
+        Returns the valid value ID for the appointment status type.
+        """
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """
+        Returns the description for the appointment status type.
+        """
+        return self._description
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["AppointmentStatusType"]:
+        """
+        Returns the enum member matching the given description (case-sensitive).
+        """
+        for member in cls:
+            if member.description == description:
+                return member
+        return None
+
+    @classmethod
+    def by_description_case_insensitive(
+        cls, description: str
+    ) -> Optional["AppointmentStatusType"]:
+        """
+        Returns the enum member matching the given description (case-insensitive).
+        """
+        desc_lower = description.lower()
+        for member in cls:
+            if member.description.lower() == desc_lower:
+                return member
+        return None
+
+    @classmethod
+    def by_valid_value_id(
+        cls, valid_value_id: int
+    ) -> Optional["AppointmentStatusType"]:
+        """
+        Returns the enum member matching the given valid value ID.
+        """
+        for member in cls:
+            if member.valid_value_id == valid_value_id:
+                return member
+        return None