Feature/bcss 20606 new regression release seek further data (#129)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description
Selenium to Playwright - Regression Tests - Subject - Seek Further Data
<!-- Describe your changes in detail. -->

## Context
Move Lynch self-referred subject to seeking Further Data (uncertified
death), then back.
Below are the lists of files where code change is implemented
1) Tests File --> test_lynch_self_referral_seeking_further_data_flow.py 
2) base_page.py
3) POM --> pages --> subject --> subject_lynch_page.py
<!-- Why is this change required? What problem does it solve? -->

## 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)
- [ ] 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.

---------

Co-authored-by: AndyG <[email protected]>
Co-authored-by: Adriano Aru <[email protected]>

Author: 3 people

classes/date/date_description_utils.py

@@ -1,4 +1,5 @@
 from datetime import datetime, timedelta, date
+from dateutil.relativedelta import relativedelta
 from typing import Optional
 import logging
 from classes.date.date_description import DateDescription
@@ -235,12 +236,129 @@ def is_valid_date(date_str: str, date_format: str) -> bool:
     @staticmethod
     def oracle_to_date_function(date_str: str, oracle_format: str) -> str:
         """
-        Constructs an Oracle TO_DATE function to convert a string to a date.
-        This method formats the date string according to the specified format.
+        Constructs a safe Oracle TO_DATE() expression from a Python date string.
         Args:
-            date_str (str): The date string to be converted.
-            oracle_format (str): The format in which the date string is provided.
+            date_str (str): The date string to be converted (e.g., '06/10/1950').
+            oracle_format (str): The Oracle format mask (e.g., 'dd/mm/yyyy').
         Returns:
-            str: The SQL expression for the Oracle TO_DATE function.
+            str: The SQL-safe TO_DATE(...) expression, or 'NULL' if date_str is None/empty.
         """
-        return f" TO_DATE( '{date_str}', '{oracle_format}') "
+        if not date_str or str(date_str).strip().lower() == "none":
+            return "NULL"
+
+        clean = str(date_str).strip().replace("\u00a0", "")
+        py_fmt = (
+            oracle_format.lower()
+            .replace("dd", "%d")
+            .replace("mm", "%m")
+            .replace("yyyy", "%Y")
+        )
+
+        # Validate in Python before sending to Oracle
+        datetime.strptime(clean, py_fmt)
+
+        return f"TO_DATE('{clean}', '{oracle_format}')"
+
+    @staticmethod
+    def convert_description_to_python_date(
+        which_date: str, date_description: str
+    ) -> Optional[date]:
+        """
+        Converts a date description (e.g. '2 years ago', '15/08/2020', 'NULL')
+        into a Python datetime.date object or None.
+        Args:
+            which_date (str): Label for logging.
+            date_description (str): Human-readable or exact date description.
+        Returns:
+            Optional[date]: The corresponding date object, or None if not applicable.
+        """
+        logging.debug(
+            f"convert_description_to_python_date: {which_date}, {date_description}"
+        )
+
+        if not date_description or date_description.strip().upper() in (
+            DateDescriptionUtils.NULL_STRING,
+            "NONE",
+        ):
+            return None
+
+        date_description = date_description.strip()
+        today = datetime.today().date()
+
+        # Try direct date formats
+        abs_date = _parse_absolute_date(date_description)
+        if abs_date:
+            return abs_date
+
+        # Try relative phrases like "3 years ago"
+        rel_date = _parse_relative_date(date_description, today)
+        if rel_date:
+            return rel_date
+
+        # Try enum-based descriptions
+        enum_date = _parse_enum_date(date_description, today)
+        if enum_date is not None:
+            return enum_date
+
+        return None
+
+
+def _parse_absolute_date(date_description: str) -> Optional[date]:
+    """
+    Tries to parse an absolute date from the description.
+    Args:
+        date_description (str): The date description to parse.
+    Returns:
+        Optional[date]: The parsed absolute date or None if parsing failed.
+    """
+    for fmt in (
+        DateDescriptionUtils.DATE_FORMAT_DD_MM_YYYY,
+        DateDescriptionUtils.DATE_FORMAT_YYYY_MM_DD,
+    ):
+        if DateDescriptionUtils.is_valid_date(date_description, fmt):
+            return datetime.strptime(date_description, fmt).date()
+    return None
+
+
+def _parse_relative_date(date_description: str, today: date) -> Optional[date]:
+    """
+    Tries to parse a relative date from the description (e.g., "3 years ago").
+    Args:
+        date_description (str): The date description to parse.
+        today (date): The reference date for relative calculations.
+    Returns:
+        Optional[date]: The parsed relative date or None if parsing failed.
+    """
+    words = date_description.split(" ")
+    if date_description.endswith(" ago") and len(words) == 3:
+        try:
+            number = int(words[0])
+            unit = words[1]
+            if "year" in unit:
+                return today - relativedelta(years=number)
+            if "month" in unit:
+                return today - relativedelta(months=number)
+            if "day" in unit:
+                return today - timedelta(days=number)
+        except Exception as e:
+            logging.warning(f"Could not parse relative date '{date_description}': {e}")
+    return None
+
+
+def _parse_enum_date(date_description: str, today: date) -> Optional[date]:
+    """
+    Tries to parse a date from the DateDescription enum.
+    Args:
+        date_description (str): The date description to parse.
+        today (date): The reference date for special cases.
+    Returns:
+        Optional[date]: The parsed enum date or None if parsing failed.
+    """
+    enum_val = DateDescription.by_description_case_insensitive(date_description)
+    if enum_val is not None:
+        if enum_val.name == DateDescriptionUtils.NULL_STRING:
+            return None
+        if enum_val.name == DateDescriptionUtils.NOT_NULL_STRING_UNDERSCORE:
+            return today
+        return enum_val.suitable_date
+    return None

classes/lynch/genetic_condition_type.py

@@ -0,0 +1,51 @@
+from enum import Enum
+from typing import Optional
+
+
+class GeneticConditionType(Enum):
+    """
+    Enum representing genetic condition types with valid value ID, description, and lower age.
+    Provides lookup by description and valid value ID.
+    """
+
+    EPCAM = (307070, "EPCAM", 25)
+    MLH1 = (306443, "MLH1", 25)
+    MSH2 = (306444, "MSH2", 25)
+    MSH6 = (306445, "MSH6", 35)
+    PMS2 = (306446, "PMS2", 35)
+
+    def __init__(self, valid_value_id: int, description: str, lower_age: int):
+        self._valid_value_id = valid_value_id
+        self._description = description
+        self._lower_age = lower_age
+
+    @property
+    def valid_value_id(self) -> int:
+        """Return the valid value ID."""
+        return self._valid_value_id
+
+    @property
+    def description(self) -> str:
+        """Return the description."""
+        return self._description
+
+    @property
+    def lower_age(self) -> int:
+        """Return the lower age."""
+        return self._lower_age
+
+    @classmethod
+    def by_description(cls, description: str) -> Optional["GeneticConditionType"]:
+        """Return the GeneticConditionType instance for the given description."""
+        for member in cls:
+            if member.description == description:
+                return member
+        return None
+
+    @classmethod
+    def by_valid_value_id(cls, valid_value_id: int) -> Optional["GeneticConditionType"]:
+        """Return the GeneticConditionType instance for the given valid value ID."""
+        for member in cls:
+            if member.valid_value_id == valid_value_id:
+                return member
+        return None

classes/repositories/general_repository.py

@@ -55,3 +55,15 @@ def run_database_transition(
             raise oracledb.DatabaseError(f"Error executing database transition: {e}")
         finally:
             self.oracle_db.disconnect_from_db(conn)
+
+    def process_new_lynch_patients(self):
+        logging.debug("[START] process_new_lynch_patients")
+        try:
+            self.oracle_db.execute_stored_procedure("pkg_lynch.p_process_patients")
+        except Exception as e:
+            logging.error("Error executing pkg_lynch.p_process_patients", exc_info=True)
+            raise oracledb.DatabaseError(
+                f"Error executing pkg_lynch.p_process_patients: {e}"
+            )
+
+        logging.debug("[END] process_new_lynch_patients")

pages/screening_subject_search/subject_screening_summary_page.py

@@ -1,7 +1,7 @@
 import re
 from playwright.sync_api import Page, expect, Locator
 from pages.base_page import BasePage
-from enum import Enum
+from enum import StrEnum
 import logging
 import pytest
 from typing import List
@@ -39,8 +39,10 @@ def __init__(self, page: Page):
         )
         self.patient_contacts = self.page.get_by_role("link", name="Patient Contacts")
         self.more = self.page.get_by_role("link", name="more")
-        self.change_screening_status = self.page.get_by_label("Change Screening Status")
-        self.reason = self.page.get_by_label("Reason", exact=True)
+        self.change_screening_status_dropdown = self.page.get_by_label(
+            "Change Screening Status"
+        )
+        self.reason_dropdown = self.page.get_by_label("Reason", exact=True)
         self.update_subject_data = self.page.get_by_role(
             "button", name="Update Subject Data"
         )
@@ -89,6 +91,9 @@ def __init__(self, page: Page):
         self.reopen_for_correction_button = self.page.get_by_role(
             "button", name="Reopen episode for correction"
         )
+        self.self_refer_lynch_surveillance_button = self.page.get_by_role(
+            "button", name="Self-refer Lynch Surveillance"
+        )
 
     def wait_for_page_title(self) -> None:
         """Waits for the page to be the Subject Screening Summary"""
@@ -188,7 +193,7 @@ def click_more(self) -> None:
 
     def click_update_subject_data(self) -> None:
         """Click on the 'Update Subject Data' button."""
-        self.click(self.update_subject_data)
+        self.safe_accept_dialog(self.update_subject_data)
 
     def click_close_fobt_screening_episode(self) -> None:
         """Click on the 'Close FOBT Screening Episode' button."""
@@ -204,11 +209,11 @@ def go_to_a_page_to_close_the_episode(self) -> None:
 
     def select_change_screening_status(self, option: str) -> None:
         """Select the given 'change screening status' option."""
-        self.change_screening_status.select_option(option)
+        self.change_screening_status_dropdown.select_option(option)
 
     def select_reason(self, option: str) -> None:
         """Select the given 'reason' option."""
-        self.reason.select_option(option)
+        self.reason_dropdown.select_option(option)
 
     def expand_episodes_list(self) -> None:
         """Click on the episodes list expander icon."""
@@ -422,14 +427,35 @@ def reopen_fobt_screening_episode(self) -> None:
         # Step 2: Safely accept the confirmation dialog triggered by the correction button
         self.safe_accept_dialog(self.reopen_for_correction_button)
 
+    def click_self_refer_lynch_surveillance_button(self) -> None:
+        """Click on the 'Self-refer Lynch Surveillance' button"""
+        self.safe_accept_dialog(self.self_refer_lynch_surveillance_button)
+        self.page.wait_for_timeout(1000)
+
+    def change_screening_status(self, status_option: str, reason_option: str) -> None:
+        """
+        Change the screening status of the subject by selecting the given status and reason options,
+        then clicking the 'Update Subject Data' button.
+
+        Args:
+            status_option (str): The option value to select for the screening status.
+            reason_option (str): The option value to select for the reason.
+        """
+        self.select_change_screening_status(status_option)
+        self.select_reason(reason_option)
+        self.click_update_subject_data()
+        self.page.wait_for_timeout(1000)
+
 
-class ChangeScreeningStatusOptions(Enum):
+class ChangeScreeningStatusOptions(StrEnum):
     """Enum for Change Screening Status options."""
 
     SEEKING_FURTHER_DATA = "4007"
+    LYNCH_SELF_REFERRAL = "307129"
 
 
-class ReasonOptions(Enum):
+class ReasonOptions(StrEnum):
     """Enum for Reason options."""
 
     UNCERTIFIED_DEATH = "11314"
+    RESET_SEEKING_FURTHER_DATA_TO_LYNCH_SELF_REFERRAL = "307135"

pytest.ini

@@ -55,3 +55,4 @@ markers =
     spine_retrieval_search_tests: tests that are part of subject spine retrieval demographics
     hub_user_tests: tests that are part of the hub user test suite
     fobt_regression_tests: tests that are part of the fobt regression test suite
+    lynch_self_referral_tests: tests that are part of the lynch self referral test suite