Feature/bcss 21306 selenium to playwirght fobtregressiontests scenario 3 (#128)

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

<!-- Describe your changes in detail. -->
Adding scenario 3 to the playwright test suite along with any relevant
utilities, classes and POMs

## Context

<!-- Why is this change required? What problem does it solve? -->
Adding scenario 3 to the playwright test suite along with any relevant
utilities, classes and POMs

## Type of changes

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

- [x] 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. -->

- [x] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [x] I have added tests to cover my changes (where appropriate)
- [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: adrianoaru-nhs

classes/pi_subject.py

@@ -1,6 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Optional
 from datetime import date
+from classes.subject import Subject
 
 
 @dataclass
@@ -69,3 +70,48 @@ def to_string(self) -> str:
             f"replaced_by_nhs_number  =    {self.replaced_nhs_number}",
         ]
         return "PISubject:\n" + "\n".join(fields)
+
+    @staticmethod
+    def from_subject(subject: "Subject") -> "PISubject":
+        """
+        Creates a PISubject object from a Subject object.
+
+        Args:
+            subject (Subject): The Subject object to convert.
+
+        Returns:
+            PISubject: The populated PISubject object.
+
+        """
+        gender = subject.get_gender()
+        if gender is not None:
+            gender_code = gender.redefined_value
+        else:
+            gender_code = 0  # If None, set to "Not known gender"
+        return PISubject(
+            screening_subject_id=subject.screening_subject_id,
+            nhs_number=subject.nhs_number,
+            family_name=subject.surname,
+            first_given_names=subject.forename,
+            other_given_names=subject.other_names,
+            previous_family_name=subject.previous_surname,
+            name_prefix=subject.title,
+            birth_date=subject.date_of_birth,
+            death_date=subject.date_of_death,
+            gender_code=gender_code,
+            address_line_1=subject.address_line1,
+            address_line_2=subject.address_line2,
+            address_line_3=subject.address_line3,
+            address_line_4=subject.address_line4,
+            address_line_5=subject.address_line5,
+            postcode=subject.postcode,
+            gnc_code=subject.registration_code,
+            gp_practice_code=subject.gp_practice_code,
+            nhais_deduction_reason=subject.nhais_deduction_reason,
+            nhais_deduction_date=subject.nhais_deduction_date,
+            exeter_system=subject.datasource,
+            removed_to=subject.removed_to_datasource,
+            pi_reference=None,
+            superseded_by_nhs_number=None,
+            replaced_nhs_number=None,
+        )

classes/repositories/subject_repository.py

@@ -103,7 +103,7 @@ def process_pi_subject(self, pio_id: int, pi_subject: PISubject) -> Optional[int
 
         return new_contact_id
 
-    def update_pi_subject(self, pi_subject: PISubject) -> None:
+    def update_pi_subject(self, pio_id: int, pi_subject: PISubject) -> None:
         """
         Updates an existing screening subject.
 
@@ -122,9 +122,7 @@ def update_pi_subject(self, pi_subject: PISubject) -> None:
             raise ValueError(
                 "A PI Reference must be specified when updating an existing subject, for example 'SELF REFERRAL' or 'AUTOMATED TEST'"
             )
-        procedure = "PKG_SSPI.p_process_pi_subject"
-        params = [pi_subject, None, None, None, None]
-        self.oracle_db.execute_stored_procedure(procedure, params)
+        self.process_pi_subject(pio_id, pi_subject)
 
     def get_active_gp_practice_in_hub_and_sc(
         self, hub_code: str, screening_centre_code: str

classes/repositories/user_repository.py

@@ -95,7 +95,7 @@ def get_role_id_for_role(self, role: "UserRoleType") -> int:
         df = self.general_query(role)
         return int(df["role_id"].iloc[0])
 
-    def get_org_code_for_role(self, role: "UserRoleType") -> int:
+    def get_org_code_for_role(self, role: "UserRoleType") -> str:
         """
         Get the ORG CODE for the role.
 
@@ -108,4 +108,4 @@ def get_org_code_for_role(self, role: "UserRoleType") -> int:
         logging.debug(f"Getting ORG CODE for role: {role.user_code}")
 
         df = self.general_query(role)
-        return int(df["org_code"].iloc[0])
+        return str(df["org_code"].iloc[0])

classes/subject.py

@@ -10,8 +10,11 @@
 from classes.sdd_reason_for_change_type import SDDReasonForChangeType
 from classes.ss_reason_for_change_type import SSReasonForChangeType
 from classes.ssdd_reason_for_change_type import SSDDReasonForChangeType
+from classes.user import User
 from utils.date_time_utils import DateTimeUtils
+from utils.oracle.oracle import OracleDB
 import pandas as pd
+import logging
 
 
 @dataclass
@@ -1302,3 +1305,34 @@ def from_dataframe_row(row: pd.Series) -> "Subject":
         }
 
         return Subject(**field_map)
+
+    def populate_subject_object_from_nhs_no(self, nhs_no: str) -> "Subject":
+        """
+        Populates a Subject object from the NHS number.
+        Args:
+            nhs_no (str): The NHS number to populate the subject from.
+        Returns:
+            Subject: A populated Subject object from the database
+        """
+        from utils.oracle.subject_selection_query_builder import (
+            SubjectSelectionQueryBuilder,
+        )
+
+        nhs_no_criteria = {"nhs number": nhs_no}
+        subject = Subject()
+        user = User()
+        builder = SubjectSelectionQueryBuilder()
+
+        query, bind_vars = builder.build_subject_selection_query(
+            criteria=nhs_no_criteria,
+            user=user,
+            subject=subject,
+            subjects_to_retrieve=1,
+        )
+
+        logging.debug(
+            "[SUBJECT ASSERTIONS] Executing base query to populate subject object"
+        )
+
+        subject_df = OracleDB().execute_query(query, bind_vars)
+        return self.from_dataframe_row(subject_df.iloc[0])

classes/user.py

@@ -1,6 +1,6 @@
 from typing import Optional
 from classes.organisation_complex import Organisation
-import pandas as pd
+from classes.user_role_type import UserRoleType
 
 
 class User:
@@ -159,3 +159,30 @@ def from_dataframe_row(self, row) -> "User":
             pio_id=row["pio_id"],
             organisation=organisation,
         )
+
+    @staticmethod
+    def from_user_role_type(user_role_type: "UserRoleType") -> "User":
+        """
+        Creates a User object from a UserRoleType object using UserRepository methods.
+
+        Args:
+            user_role_type (UserRoleType): The UserRoleType object.
+
+        Returns:
+            User: The constructed User object.
+        """
+        from classes.repositories.user_repository import UserRepository
+
+        user_repo = UserRepository()
+        pio_id = user_repo.get_pio_id_for_role(user_role_type)
+        role_id = user_repo.get_role_id_for_role(user_role_type)
+        org_id = user_repo.get_org_id_for_role(user_role_type)
+        org_code = user_repo.get_org_code_for_role(user_role_type)
+
+        organisation = Organisation(new_id=org_id, new_code=str(org_code))
+        return User(
+            user_id=pio_id,
+            role_id=role_id,
+            pio_id=pio_id,
+            organisation=organisation,
+        )

docs/utility-guides/SSPIChangeSteps.md

@@ -0,0 +1,70 @@
+# Utility Guide: SSPIChangeSteps
+
+The `SSPIChangeSteps` utility provides a simple interface for simulating an SSPI update to change a subject's date of birth in the BCSS system. This is particularly useful for automated testing scenarios where you need to set a subject's age to a specific value.
+
+---
+
+## Table of Contents
+
+- [Utility Guide: SSPIChangeSteps](#utility-guide-sspichangesteps)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Example Usage](#example-usage)
+  - [Method Reference](#method-reference)
+  - [Implementation Details](#implementation-details)
+
+---
+
+## Overview
+
+The main method provided by this utility is:
+
+```python
+sspi_update_to_change_dob_received(nhs_no: str, age_to_change_to: int)
+```
+
+This method will:
+
+- Retrieve the subject by NHS number.
+- Calculate the correct date of birth for the specified age (taking leap years into account).
+- Update the subject's date of birth in the database as if it was received from an SSPI update.
+
+## Example Usage
+
+```python
+from utils.sspi_change_steps import SSPIChangeSteps
+
+nhs_no = "1234567890"
+target_age = 75
+
+SSPIChangeSteps().sspi_update_to_change_dob_received(nhs_no, target_age)
+```
+
+This will update the subject with NHS number `1234567890` to have an age of 75.
+
+---
+
+## Method Reference
+
+`sspi_update_to_change_dob_received`
+
+```python
+def sspi_update_to_change_dob_received(nhs_no: str, age_to_change_to: int) -> None
+```
+
+**Parameters:**
+
+- `nhs_no` (str): The NHS number of the subject to update.
+- `age_to_change_to` (int): The age to change the subject's date of birth to.
+
+**Description:**
+
+Calculates the correct date of birth for the given age and updates the subject in the database as if the change was received from an SSPI update.
+
+---
+
+## Implementation Details
+
+- The utility uses the `Subject` and `PISubject` classes to represent and update subject data.
+- The date of birth is calculated using `DateTimeUtils.calculate_birth_date_for_age`, which ensures the correct age is set, accounting for leap years.
+- The update is performed as the automated process user (user ID 2).

pages/screening_practitioner_appointments/appointment_detail_page.py

@@ -1,5 +1,6 @@
 from playwright.sync_api import Page, expect
 from pages.base_page import BasePage
+from enum import StrEnum
 
 
 class AppointmentDetailPage(BasePage):
@@ -13,6 +14,10 @@ def __init__(self, page: Page):
         self.attended_check_box = self.page.locator("#UI_ATTENDED")
         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(
+            "Reason for Cancellation"
+        )
 
     def check_attendance_radio(self) -> None:
         """Checks the attendance radio button."""
@@ -26,9 +31,16 @@ def click_calendar_button(self) -> None:
         """Clicks the calendar button."""
         self.click(self.calendar_button)
 
-    def click_save_button(self) -> None:
-        """Clicks the save button."""
-        self.click(self.save_button)
+    def click_save_button(self, accept_dialog: bool = False) -> None:
+        """
+        Clicks the save button.
+        Args:
+            accept_dialog (bool): Whether to accept the dialog.
+        """
+        if accept_dialog:
+            self.safe_accept_dialog(self.save_button)
+        else:
+            self.click(self.save_button)
 
     def verify_text_visible(self, text: str) -> None:
         """Verifies that the specified text is visible on the page."""
@@ -60,3 +72,30 @@ def wait_for_attendance_radio(self, timeout_duration: float = 30000) -> None:
                 timeout_duration - elapsed if timeout_duration - elapsed > 0 else 1000
             )
         )
+
+    def check_cancel_radio(self) -> None:
+        """Checks the cancel radio button."""
+        self.cancel_radio.check()
+
+    def select_reason_for_cancellation_option(self, option: str) -> None:
+        """
+        Selects the reason for cancellation from the dropdown.
+        Args:
+            option: The reason for cancellation to select.
+            The options are in the ReasonForCancellationOptions class
+        """
+        self.reason_for_cancellation_dropwdown.select_option(value=option)
+
+
+class ReasonForCancellationOptions(StrEnum):
+    """Enum for cancellation reason options"""
+
+    PATIENT_REQUESTS_DISCHARGE_FROM_SCREENING = "6008"
+    PATIENT_UNSUITABLE_RECENTLY_SCREENED = "6007"
+    PATIENT_UNSUITABLE_CURRENTLY_UNDERGOING_TREATMENT = "6006"
+    PATIENT_CANCELLED_TO_CONSIDER = "6005"
+    PATIENT_CANCELLED_MOVED_OUT_OF_AREA = "6003"
+    SCREENING_CENTRE_CANCELLED_OTHER_REASON = "6002"
+    CLINIC_UNAVAILABLE = "6001"
+    PRACTITIONER_UNAVAILABLE = "6000"
+    PATIENT_CANCELLED_OTHER_REASON = "6004"

pages/screening_subject_search/reopen_fobt_screening_episode_page.py

@@ -0,0 +1,18 @@
+from playwright.sync_api import Page
+from pages.base_page import BasePage
+
+
+class ReopenFOBTScreeningEpisodePage(BasePage):
+    """Reopen FOBT Screening Episode Page locators, and methods for interacting with the page."""
+
+    def __init__(self, page: Page):
+        super().__init__(page)
+        self.page = page
+
+        self.reopen_to_book_an_assessment_button = self.page.get_by_role(
+            "button", name="Reopen to book an assessment"
+        )
+
+    def click_reopen_to_book_an_assessment_button(self) -> None:
+        """Click the 'Reopen to book an assessment' button."""
+        self.safe_accept_dialog(self.reopen_to_book_an_assessment_button)

pages/screening_subject_search/subject_screening_summary_page.py

@@ -83,6 +83,9 @@ def __init__(self, page: Page):
         self.latest_event_status_cell = self.page.locator(
             "td.epihdr_label:text('Latest Event Status') + td.epihdr_data"
         )
+        self.reopen_fobt_screening_episode_button = self.page.get_by_role(
+            "button", name="Reopen FOBT Screening Episode"
+        )
 
     def wait_for_page_title(self) -> None:
         """Waits for the page to be the Subject Screening Summary"""
@@ -393,6 +396,10 @@ def assert_latest_event_status(self, expected_status: str) -> None:
             actual_status == expected_status
         ), f"[LATEST EVENT STATUS MISMATCH] Expected '{expected_status}', but found '{actual_status}' in UI."
 
+    def click_reopen_fobt_screening_episode_button(self) -> None:
+        """Click on the 'Reopen FOBT Screening Episode' button"""
+        self.click(self.reopen_fobt_screening_episode_button)
+
 
 class ChangeScreeningStatusOptions(Enum):
     """Enum for Change Screening Status options."""

tests/regression/regression_tests/fobt_regression_tests/test_scenario_1.py

@@ -52,12 +52,12 @@ def test_scenario_1(page: Page) -> None:
         "age (y/d)": "65/25",
         "active gp practice in hub/sc": "BCS01/BCS001",
     }
-    nhs_no = CreateSubjectSteps().create_custom_subject(requirements, user_role)
+    nhs_no = CreateSubjectSteps().create_custom_subject(requirements)
     if nhs_no is None:
         raise ValueError("NHS No is 'None'")
 
     # Then Comment: NHS number
-    logging.info(f"Created subject's NHS number: {nhs_no}")
+    logging.info(f"[SUBJECT CREATION] Created subject's NHS number: {nhs_no}")
 
     # Then my subject has been updated as follows:
     criteria = {