Merge branch 'main' into feature/BCSS-21307-fobt-regression-tests-scenario-5

Signed-off-by: AndyG <[email protected]>

Author: Andyg79

.gitleaksignore

@@ -225,3 +225,4 @@ cae84544e2852202f5d0abb9ad18f9d83a0c6d80:subject_criteria_builder/criteria.json:
 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

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.
 

docs/SubjectCriteriaBuilderApllication.md

@@ -0,0 +1,263 @@
+# Subject Criteria Builder Application
+
+This application is a Streamlit-based tool for interactively building subject selection criteria for the NHS BCSS system. It allows users to search, select, and configure criteria keys, view descriptions, choose from allowed values, and copy the resulting criteria as JSON. It also generates the corresponding SQL query and, if required, allows you to select a user or enter a subject's NHS number to populate the query context.
+
+---
+
+## Table of Contents
+
+- [Subject Criteria Builder Application](#subject-criteria-builder-application)
+  - [Table of Contents](#table-of-contents)
+  - [How to Use the Application](#how-to-use-the-application)
+    - [Pre-requisites](#pre-requisites)
+    - [Launching the App](#launching-the-app)
+    - [Searching for Criteria](#searching-for-criteria)
+    - [Selecting and Configuring a Criterion](#selecting-and-configuring-a-criterion)
+    - [User and Subject Dependencies](#user-and-subject-dependencies)
+    - [Copying the Criteria](#copying-the-criteria)
+    - [Resetting the Builder and Hiding Criteria](#resetting-the-builder-and-hiding-criteria)
+  - [Maintaining the Application](#maintaining-the-application)
+    - [Updating `criteria.json`](#updating-criteriajson)
+      - [To add a new criterion](#to-add-a-new-criterion)
+      - [To edit a criterion](#to-edit-a-criterion)
+      - [To remove a criterion](#to-remove-a-criterion)
+      - [About the `dependencies` field](#about-the-dependencies-field)
+    - [Adding New Criteria Keys](#adding-new-criteria-keys)
+    - [Editing Allowed Values or Descriptions](#editing-allowed-values-or-descriptions)
+    - [Troubleshooting](#troubleshooting)
+  - [Example Entry in `criteria.json`](#example-entry-in-criteriajson)
+  - [Summary](#summary)
+
+---
+
+## How to Use the Application
+
+### Pre-requisites
+
+Before running the application, you must create a `local.env` file containing your Oracle database credentials.<br>
+You can generate a template for this file by running:
+
+```bash
+python setup_env_file.py
+```
+
+After running the script, open the generated `local.env` file and populate the following fields with your Oracle credentials:
+
+```env
+ORACLE_USERNAME=your_oracle_username
+ORACLE_DB=your_oracle_db
+ORACLE_PASS=your_oracle_password
+```
+
+These credentials are required for the application to connect to the Oracle database and populate user and subject objects.
+
+---
+
+### Launching the App
+
+1. **Open a terminal** in the project root directory.
+2. Run the following command:  `streamlit run subject_criteria_builder.py`
+3. The app will open in your default web browser.
+4. You can also copy and paste the `Local URL` into a browser to access the app.
+
+---
+
+### Searching for Criteria
+
+- Use the **search bar** at the top to filter criteria keys by name or description.
+- The list updates as you type, showing only matching criteria.
+- You can hide or show the search bar and criteria list using the "Hide Criteria/Search" and "Show Criteria/Search" buttons at the top.
+
+---
+
+### Selecting and Configuring a Criterion
+
+1. **Expand a criterion** by clicking the ➕ button next to its name.
+2. The expanded section shows:
+   - **Description:** An explanation of what the key is and what input is expected.
+   - **Dropdown:** If the key has a set of allowed values (from `criteria.json`), a dropdown will appear for you to select from.
+   - **Text Input:** You can always enter a custom value, even if a dropdown is present.
+3. **Collapse** the criterion by clicking the ✖ button.
+
+---
+
+### User and Subject Dependencies
+
+Some criteria require additional context, such as a User or Subject object.<br>
+If you select a criterion that has a dependency on "User" or "Subject" (as defined in `criteria.json`):
+
+- **User Dependency:**
+  - A section will appear allowing you to select a user from the list defined in `users.json`.
+  - Once selected, the user's name and username are displayed, and a populated user object is created for use in the SQL query.
+
+- **Subject Dependency:**
+  - A section will appear allowing you to enter a subject's NHS number.
+  - Once entered, the application will attempt to populate a subject object using this NHS number for use in the SQL query.
+
+These sections will remain visible as long as any selected criteria require them.
+
+---
+
+### Copying the Criteria
+
+- As you configure criteria, the **Final Criteria Dictionary** at the bottom updates in real time.
+- To copy the criteria you can either select the whole code block manually or click on the copy button that is at the top right of this code block.
+
+---
+
+### Resetting the Builder and Hiding Criteria
+
+- Click the **🔄 Reset Criteria Builder** button at the top to clear all selections and start over.
+- Use the **🙈 Hide Criteria/Search** and **👁️ Show Criteria/Search** buttons to hide or show the search bar and criteria list.
+
+---
+
+## Maintaining the Application
+
+### Updating `criteria.json`
+
+The file `subject_criteria_builder/criteria.json` defines all available criteria keys, their descriptions, allowed values, and dependencies.
+
+Each entry in the file looks like this:
+
+```json
+{
+  "key": "NHS_NUMBER",
+  "value_source": "",
+  "notes": "Enter the 10-digit NHS Number of the subject you want to search for."
+}
+```
+
+Or, with allowed values and dependencies:
+
+```json
+{
+  "key": "SUBJECT_HUB_CODE",
+  "value_source": "SubjectHubCode.by_description",
+  "notes": "Select the hub or organisation for the subject.",
+  "allowed_values": [
+    "user's hub",
+    "user's organisation"
+  ],
+  "dependencies": [
+    "User"
+  ]
+}
+```
+
+- **`key`:** The unique identifier for the criterion (must match the code).
+- **`value_source`:** (Optional) The source of the value, can be left blank. This refers to the class + method used in the subject selection query builder. This is not used by the code but is there to allow easier tracking/mapping.
+- **`notes`:** A clear, user-focused description of what the key is and what the user should input.
+- **`allowed_values`:** (Optional) An array of allowed values for the dropdown selection.
+- **`dependencies`:** (Optional) An array that can include `"User"` and/or `"Subject"`. If present, the app will prompt for a user selection or subject NHS number as needed.
+
+#### To add a new criterion
+
+1. Add a new object to the JSON array with the following fields:
+   - `"key"`: The `Enum` member name (must match the code).
+   - `"value_source"`: (Optional) The value source, can be left blank.
+   - `"notes"`: A clear, user-focused description of what the key is and what the user should input.
+   - `"allowed_values"`: (Optional) An array of allowed values for the dropdown selection.
+   - `"dependencies"`: (Optional) An array containing `"User"` and/or `"Subject"` if the criterion requires additional context.
+
+2. Save the file. The app will automatically pick up the new key on reload.
+
+#### To edit a criterion
+
+- Find the object with the matching `"key"` and update the `"notes"`, `"allowed_values"`, or `"dependencies"` as needed.
+- Save the file and reload the app.
+
+#### To remove a criterion
+
+- Delete the object from the JSON array.
+- Save the file and reload the app.
+
+#### About the `dependencies` field
+
+- If a criterion requires a User or Subject context, add a `"dependencies"` array to its entry, e.g.:
+
+  ```json
+  "dependencies": ["User"]
+  ```
+
+  or
+
+  ```json
+  "dependencies": ["Subject"]
+  ```
+
+  or both:
+
+  ```json
+  "dependencies": ["User", "Subject"]
+  ```
+
+- The application will automatically show the relevant input sections when any selected criteria require these dependencies.
+
+---
+
+### Adding New Criteria Keys
+
+If you add new keys to the `SubjectSelectionCriteriaKey` `Enum` in your code, you should also add a corresponding entry in `criteria.json` with a description (`notes`), and (optionally) allowed values and dependencies.
+
+---
+
+### Editing Allowed Values or Descriptions
+
+- **Allowed Values:** Update the `"allowed_values"` array for any key to change the dropdown options shown to users.
+- **Descriptions:** Update the `"notes"` field to clarify what the key is for or what input is expected.
+- **Dependencies:** Update the `"dependencies"` array to control when the app prompts for user or subject context.
+
+---
+
+### Troubleshooting
+
+- **A key does not appear in the UI:**
+  Ensure it exists in both the `SubjectSelectionCriteriaKey` `Enum` and in `criteria.json`.
+
+- **Dropdown is missing for a key:**
+  Add or update the `"allowed_values"` array for that key in `criteria.json`.
+
+- **Descriptions are unclear or missing:**
+  Update the `"notes"` field for the relevant key in `criteria.json`.
+
+- **App does not reload changes:**
+  Save your changes and refresh the `Streamlit` app in your browser.
+
+- **Copy to clipboard does not work:**
+  Some browsers may not support auto-copy. Manually select and copy the JSON from the code block.
+
+- **Oracle DB errors:**
+  Ensure your `local.env` file is present and contains valid values for `ORACLE_USERNAME`, `ORACLE_DB`, and `ORACLE_PASS`.
+
+---
+
+## Example Entry in `criteria.json`
+
+```json
+{
+  "key": "SCREENING_STATUS",
+  "value_source": "ScreeningStatusType.by_description_case_insensitive",
+  "notes": "Select the current screening status for the subject.",
+  "allowed_values": [
+    "Call",
+    "Inactive",
+    "Opt-in",
+    "Recall",
+    "Self-referral",
+    "Surveillance",
+    "Ceased"
+  ],
+  "dependencies": ["Subject"]
+}
+```
+
+---
+
+## Summary
+
+- **All configuration is driven by `criteria.json`.**
+- **Descriptions, allowed values, and dependencies are fully customizable.**
+- **No code changes are needed for most updates—just edit the JSON file.**
+- **For new `Enum` keys, add them to both the `SubjectSelectionCriteriaKey` `Enum` and the JSON.**
+- **For criteria that require user or subject context, use the `dependencies` field.**