Merge branch 'main' into feature/BCSS-20586-selenium-to-playwright-organisation

# Conflicts:
#	.gitleaksignore

Author: mepr1

.gitleaksignore

@@ -221,4 +221,6 @@ 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
+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

.idea/.gitignore

@@ -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.**

docs/SubjectCriteriaBuilderApllication.md

@@ -256,7 +256,7 @@ def assert_dialog_text(self, expected_text: str, accept: bool = False) -> None:
         If no dialog appears, logs an error.
         Args:
             expected_text (str): The text that should be present in the dialog.
-            accept (bool): Set to True if you want to accept the dialog, by deafult is is set to False.
+            accept (bool): Set to True if you want to accept the dialog, by default is is set to False.
         """
         self._dialog_assertion_error = None
 
@@ -265,7 +265,7 @@ def handle_dialog(dialog: Dialog, accept: bool = False):
             Handles the dialog and asserts that the dialog contains the expected text.
             Args:
                 dialog (Dialog): the playwright dialog object
-                accept (bool): Set to True if you want to accept the dialog, by deafult is is set to False.
+                accept (bool): Set to True if you want to accept the dialog, by default is is set to False.
             """
             logging.info(f"Dialog appeared with message: {dialog.message}")
             actual_text = dialog.message

pages/base_page.py

@@ -15,7 +15,7 @@ def __init__(self, page: Page):
         self.calendar_button = self.page.get_by_role("button", name="Calendar")
         self.save_button = self.page.get_by_role("button", name="Save")
         self.cancel_radio = self.page.get_by_role("radio", name="Cancel")
-        self.reason_for_cancellation_dropwdown = self.page.get_by_label(
+        self.reason_for_cancellation_dropdown = self.page.get_by_label(
             "Reason for Cancellation"
         )
 
@@ -84,7 +84,7 @@ def select_reason_for_cancellation_option(self, option: str) -> None:
             option: The reason for cancellation to select.
             The options are in the ReasonForCancellationOptions class
         """
-        self.reason_for_cancellation_dropwdown.select_option(value=option)
+        self.reason_for_cancellation_dropdown.select_option(value=option)
 
 
 class ReasonForCancellationOptions(StrEnum):

pages/screening_practitioner_appointments/appointment_detail_page.py

@@ -0,0 +1,34 @@
+from pages.base_page import BasePage
+from playwright.sync_api import Page
+
+
+class CloseFobtScreeningEpisodePage(BasePage):
+    """Close FOBT Screening Episode Page locators, and methods for interacting with the page."""
+
+    def __init__(self, page: Page):
+        super().__init__(page)
+        self.page = page
+        self.close_fobt_screening_episode_button = self.page.get_by_role(
+            "button", name="Close FOBT Screening Episode"
+        )
+        self.reason_dropdown = self.page.locator("#CLOSE_REASON")
+        self.notes_textarea = self.page.locator("#UI_NOTES_TEXT")
+        self.final_close_button = self.page.locator("#UI_BUTTON_CLOSE")
+
+    def close_fobt_screening_episode(self, reason_text: str) -> None:
+        """
+        Complete the process of closing a FOBT screening episode.
+        Args:
+            reason_text (str): The visible text of the reason to select from the dropdown.
+        """
+        # Step 1: Trigger the dialog and accept it
+        self.safe_accept_dialog(self.close_fobt_screening_episode_button)
+
+        # Step 2: Select reason from dropdown
+        self.reason_dropdown.select_option(label=reason_text)
+
+        # Step 3: Enter note
+        self.notes_textarea.fill("automation test note")
+
+        # Step 4: Click final 'Close Episode' button
+        self.safe_accept_dialog(self.final_close_button)

pages/screening_subject_search/close_fobt_screening_episode_page.py

@@ -10,8 +10,10 @@ class RecordDiagnosisDatePage(BasePage):
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
+
         # Record Diagnosis Date - page locators
         self.diagnosis_date_field = self.page.locator("#diagnosisDate")
+        self.reason_dropdown = self.page.locator("#reason")
         self.save_button = self.page.get_by_role("button", name="Save")
 
     def enter_date_in_diagnosis_date_field(self, date: datetime) -> None:
@@ -41,3 +43,22 @@ def get_alert_message(self) -> str:
             return self.alert_message.inner_text()
         else:
             return ""
+
+    def record_diagnosis_reason(self, reason_text: str) -> None:
+        """
+        Selects a diagnosis reason from the dropdown and saves the form.
+
+        Args:
+            reason_text (str): The visible text of the reason to select.
+                Valid options include:
+                - "Patient declined all appointments"
+                - "2 DNAs of colonoscopy assessment appt"
+                - "Patient emigrated"
+                - "Patient deceased"
+                - "Patient choice"
+                - "Patient could not be contacted"
+                - "Reopened old episode, date unknown"
+                - "Other"
+        """
+        self.reason_dropdown.select_option(label=reason_text)
+        self.safe_accept_dialog(self.save_button)