Fixing file formatting errors and adding util guide

Author: adrianoaru-nhs

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_subject_search/reopen_fobt_screening_episode_page.py

@@ -1,18 +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)
+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)

utils/sspi_change_steps.py

@@ -1,54 +1,54 @@
-import logging
-from datetime import date
-from typing import Optional
-from classes.subject import Subject
-from classes.repositories.subject_repository import SubjectRepository
-from classes.pi_subject import PISubject
-from utils.date_time_utils import DateTimeUtils
-
-
-class SSPIChangeSteps:
-    def sspi_update_to_change_dob_received(
-        self, nhs_no: str, age_to_change_to: int
-    ) -> None:
-        """
-        Receives an SSPI update to change the subject's date of birth to the specified age.
-        Args:
-            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.
-        """
-        logging.debug(
-            f"start: sspi_update_to_change_dob_received(age_to_change_to={age_to_change_to})"
-        )
-
-        subject = Subject().populate_subject_object_from_nhs_no(nhs_no)
-        # Calculate the new birth date
-        birth_date = DateTimeUtils.calculate_birth_date_for_age(age_to_change_to)
-        logging.debug(f"change date of birth to: {birth_date}")
-
-        # Pass control to handle_update to make the DB changes
-        self.handle_update(subject, birth_date)
-
-        logging.debug("exit: sspi_update_to_change_dob_received()")
-
-    def handle_update(self, subject, birth_date: Optional[date]) -> None:
-        """
-        Performs the SSPI update to make the changes in the database.
-        Args:
-            subject (Subject): The subject object to update.
-            birth_date (Optional[date]): The new birth date to set.
-        """
-        logging.debug("start: handle_update(Subject, date)")
-
-        subject_repo = SubjectRepository()
-
-        pi_subject = PISubject().from_subject(subject)
-        pi_subject.pi_reference = "AUTOMATED TEST"
-        # Check if a date of birth change needs to be made first
-        if birth_date is not None:
-            pi_subject.birth_date = birth_date
-
-        # Run the update into the DB (SSPI updates are always run as automated process user 2)
-        subject_repo.update_pi_subject(2, pi_subject)
-
-        logging.debug("exit: handle_update()")
+import logging
+from datetime import date
+from typing import Optional
+from classes.subject import Subject
+from classes.repositories.subject_repository import SubjectRepository
+from classes.pi_subject import PISubject
+from utils.date_time_utils import DateTimeUtils
+
+
+class SSPIChangeSteps:
+    def sspi_update_to_change_dob_received(
+        self, nhs_no: str, age_to_change_to: int
+    ) -> None:
+        """
+        Receives an SSPI update to change the subject's date of birth to the specified age.
+        Args:
+            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.
+        """
+        logging.debug(
+            f"start: sspi_update_to_change_dob_received(age_to_change_to={age_to_change_to})"
+        )
+
+        subject = Subject().populate_subject_object_from_nhs_no(nhs_no)
+        # Calculate the new birth date
+        birth_date = DateTimeUtils.calculate_birth_date_for_age(age_to_change_to)
+        logging.debug(f"change date of birth to: {birth_date}")
+
+        # Pass control to handle_update to make the DB changes
+        self.handle_update(subject, birth_date)
+
+        logging.debug("exit: sspi_update_to_change_dob_received()")
+
+    def handle_update(self, subject, birth_date: Optional[date]) -> None:
+        """
+        Performs the SSPI update to make the changes in the database.
+        Args:
+            subject (Subject): The subject object to update.
+            birth_date (Optional[date]): The new birth date to set.
+        """
+        logging.debug("start: handle_update(Subject, date)")
+
+        subject_repo = SubjectRepository()
+
+        pi_subject = PISubject().from_subject(subject)
+        pi_subject.pi_reference = "AUTOMATED TEST"
+        # Check if a date of birth change needs to be made first
+        if birth_date is not None:
+            pi_subject.birth_date = birth_date
+
+        # Run the update into the DB (SSPI updates are always run as automated process user 2)
+        subject_repo.update_pi_subject(2, pi_subject)
+
+        logging.debug("exit: handle_update()")