Addressed feeback given in the Jira ticket

Author: adrianoaru-nhs

docs/utility-guides/SubjectDemographics.md

@@ -1,45 +1,85 @@
 # Utility Guide: Subject Demographics
 
-The Subject Demographics utility allows for different updates to subjects to be made.<br>
-This includes the following:
+The Subject Demographics utility provides helper methods for interacting with and updating subject demographic data within the BCSS Playwright automation framework.<br>
+This includes:
 
-1. Updating a subjects DOB to the following age ranges:
-   1. 50-70
-   2. 75-100
+1. Updating a subject's date of birth (DOB) to a random value within specific age ranges.
+2. Navigating to the subject demographic page and updating fields such as postcode and DOB.
 
 ## Table of Contents
 
 - [Utility Guide: Subject Demographics](#utility-guide-subject-demographics)
   - [Table of Contents](#table-of-contents)
-  - [Using the Subject Demographics class](#using-the-subject-demographics-class)
+  - [Using the SubjectDemographicUtil class](#using-the-subjectdemographicutil-class)
   - [Updating DOB](#updating-dob)
-    - [Required Args](#required-args)
+    - [Arguments](#arguments)
     - [How to use this method](#how-to-use-this-method)
+  - [Other Utility Methods](#other-utility-methods)
 
-## Using the Subject Demographics class
+## Using the SubjectDemographicUtil class
 
-You can initialise the Subject Demographics class by using the following code in your test file:
+You can initialise the SubjectDemographicUtil class by using the following code in your test file:
 
-    from utils.subject_demographics import SubjectDemographicUtil
+```python
+from utils.subject_demographics import SubjectDemographicUtil
+```
 
 ## Updating DOB
 
-Inside of the SubjectDemographicUtil class there is a method called `update_subject_dob`.<br>
-This is used to update the date of birth of a subject to a random age between 50-70 and 75-100 depending on if the argument `younger_subject` is set to True or False.<br>
-This method will navigate to the subject demographic page automatically and can be called from any page.
+The `update_subject_dob` method allows you to update a subject's date of birth, either to a specific value or to a random value within a chosen age range. The method will automatically navigate to the subject demographic page, fill in required fields (such as postcode if missing), and update the DOB.
 
-### Required Args
+### Arguments
 
-- nhs_no:
+- `nhs_no`:
   - Type: `str`
-  - This is the NHS number of the subject you want to update
-- younger_subject:
+  - The NHS number of the subject you want to update.
+- `random_dob`:
   - Type: `bool`
-  - Whether you want the subject to be younger (50-70) or older (75-100).
+  - If `True`, the DOB will be set to a random value within the specified age range.
+  - If `False`, the DOB will be set to the value provided in `new_dob`.
+- `younger_subject`:
+  - Type: `bool | None`
+  - Determines the age range for the random DOB update (only used if `random_dob` is `True`):
+    - `True`: Random age between 50-70 years old.
+    - `False`: Random age between 75-100 years old.
+    - `None`: Defaults to `False` (75-100 years old).
+- `new_dob`:
+  - Type: `datetime | None`
+  - The new date of birth to set (only used if `random_dob` is `False`).
 
 ### How to use this method
 
-To use this method simply import the SubjectDemographicUtil class and call this method, providing the two arguments:
+To update a subject's DOB to a random value between 50-70:
 
-    nhs_no = "9468743977"
-    SubjectDemographicUtil(page).update_subject_dob(nhs_no, False)
+```python
+nhs_no = "9468743977"
+SubjectDemographicUtil(page).update_subject_dob(nhs_no, random_dob=True, younger_subject=True)
+```
+
+To update a subject's DOB to a random value between 75-100:
+
+```python
+nhs_no = "9468743977"
+SubjectDemographicUtil(page).update_subject_dob(nhs_no, random_dob=True, younger_subject=False)
+```
+
+To update a subject's DOB to a specific date:
+
+```python
+from datetime import datetime
+nhs_no = "9468743977"
+new_dob = datetime(1960, 5, 15)
+SubjectDemographicUtil(page).update_subject_dob(nhs_no, random_dob=False, new_dob=new_dob)
+```
+
+## Other Utility Methods
+
+- `random_dob_within_range(younger: bool) -> datetime`
+  - Generates a random date of birth within the specified age range:
+    - If `younger` is `True`, returns a DOB for age 50-70.
+    - If `younger` is `False`, returns a DOB for age 75-100.
+
+- `random_datetime(start: datetime, end: datetime) -> datetime`
+  Generates a random datetime between two datetime objects.
+
+Refer to the source code in `utils/subject_demographics.py` for more details on available methods and their usage.

tests/smokescreen/test_compartment_6.py

@@ -44,7 +44,7 @@ def test_compartment_6(page: Page, smokescreen_properties: dict) -> None:
     logging.info("Fetched subjects for investigation dataset updates.")
     nhs_no = subjects_df["subject_nhs_number"].iloc[0]
     logging.info(f"Selected NHS number for older subject: {nhs_no}")
-    SubjectDemographicUtil(page).update_subject_dob(nhs_no, False)
+    SubjectDemographicUtil(page).update_subject_dob(nhs_no, True, False)
     logging.info(
         f"Updated date of birth for NHS number {nhs_no} to indicate an older subject."
     )
@@ -65,7 +65,7 @@ def test_compartment_6(page: Page, smokescreen_properties: dict) -> None:
     logging.info("High-risk result for a younger subject")
     nhs_no = subjects_df["subject_nhs_number"].iloc[1]
     logging.info(f"Selected NHS number for younger subject: {nhs_no}")
-    SubjectDemographicUtil(page).update_subject_dob(nhs_no, True)
+    SubjectDemographicUtil(page).update_subject_dob(nhs_no, True, True)
     logging.info(
         f"Updated date of birth for NHS number {nhs_no} to indicate a younger subject."
     )
@@ -86,7 +86,7 @@ def test_compartment_6(page: Page, smokescreen_properties: dict) -> None:
     logging.info("LNPCP result for an older subject")
     nhs_no = subjects_df["subject_nhs_number"].iloc[2]
     logging.info(f"Selected NHS number for older subject: {nhs_no}")
-    SubjectDemographicUtil(page).update_subject_dob(nhs_no, False)
+    SubjectDemographicUtil(page).update_subject_dob(nhs_no, True, False)
     logging.info(
         f"Updated date of birth for NHS number {nhs_no} to indicate an older subject."
     )
@@ -105,12 +105,16 @@ def test_compartment_6(page: Page, smokescreen_properties: dict) -> None:
     logging.info("LNPCP result for a younger subject")
     nhs_no = subjects_df["subject_nhs_number"].iloc[3]
     logging.info(f"Selected NHS number for younger subject: {nhs_no}")
-    SubjectDemographicUtil(page).update_subject_dob(nhs_no, True)
-    logging.info(f"Updated date of birth for NHS number {nhs_no} to indicate a younger subject.")
+    SubjectDemographicUtil(page).update_subject_dob(nhs_no, True, True)
+    logging.info(
+        f"Updated date of birth for NHS number {nhs_no} to indicate a younger subject."
+    )
     InvestigationDatasetCompletion(page).complete_with_result(
         nhs_no, InvestigationDatasetResults.LNPCP
     )
-    logging.info(f"Completed investigation dataset for NHS number {nhs_no} with result: LNPCP.")
+    logging.info(
+        f"Completed investigation dataset for NHS number {nhs_no} with result: LNPCP."
+    )
     AfterInvestigationDatasetComplete(page).progress_episode_based_on_result(
         InvestigationDatasetResults.LNPCP, True
     )
@@ -129,7 +133,9 @@ def test_compartment_6(page: Page, smokescreen_properties: dict) -> None:
     AfterInvestigationDatasetComplete(page).progress_episode_based_on_result(
         InvestigationDatasetResults.NORMAL, True
     )
-    logging.info(f"Progressed episode for NHS number {nhs_no_normal} based on result: NORMAL.")
+    logging.info(
+        f"Progressed episode for NHS number {nhs_no_normal} based on result: NORMAL."
+    )
     # Batch processing for result letters
     logging.info("Starting batch processing for result letters.")
     batch_processing(

utils/subject_demographics.py

@@ -19,22 +19,26 @@ class SubjectDemographicUtil:
     def __init__(self, page: Page):
         self.page = page
 
-    def update_subject_dob(self, nhs_no: str, younger_subject: bool) -> None:
+    def update_subject_dob(
+        self,
+        nhs_no: str,
+        random_dob: bool = False,
+        younger_subject: bool | None = None,
+        new_dob: datetime | None = None,
+    ) -> None:
         """
         Navigates to the subject demographics page and updates a subject's date of birth.
 
         Args:
             nhs_no (str): The NHS number of the subject you want to update.
             younger_subject (bool): Whether you want the subject to be younger (50-70) or older (75-100).
         """
-        if younger_subject:
-            end_date = datetime.today() - relativedelta(years=50)
-            start_date = datetime.today() - relativedelta(years=70)
-            date = self.random_datetime(start_date, end_date)
+        if random_dob:
+            date = self.random_dob_within_range(
+                younger_subject if younger_subject is not None else False
+            )
         else:
-            end_date = datetime.today() - relativedelta(years=75)
-            start_date = datetime.today() - relativedelta(years=100)
-            date = self.random_datetime(start_date, end_date)
+            date = new_dob
 
         logging.info(f"Navigating to subject demographic page for: {nhs_no}")
         BasePage(self.page).click_main_menu_link()
@@ -55,11 +59,35 @@ def update_subject_dob(self, nhs_no: str, younger_subject: bool) -> None:
 
         current_dob = SubjectDemographicPage(self.page).get_dob_field_value()
         logging.info(f"Current DOB: {current_dob}")
-        SubjectDemographicPage(self.page).fill_dob_input(date)
+        if date is not None:
+            SubjectDemographicPage(self.page).fill_dob_input(date)
+        else:
+            raise ValueError("Date of birth is None. Cannot fill DOB input.")
         SubjectDemographicPage(self.page).click_update_subject_data_button()
         updated_dob = SubjectDemographicPage(self.page).get_dob_field_value()
         logging.info(f"Updated DOB: {updated_dob}")
 
+    def random_dob_within_range(self, younger: bool) -> datetime:
+        """
+        Generate a random date of birth within a specified range.
+
+        Args:
+            younger (bool): If True, generate a date of birth for a subject aged between 50 and 70.
+                            If False, generate a date of birth for a subject aged between 75 and 100.
+
+        Returns:
+            datetime: the newly generated date of birth
+        """
+        if younger:
+            end_date = datetime.today() - relativedelta(years=50)
+            start_date = datetime.today() - relativedelta(years=70)
+            date = self.random_datetime(start_date, end_date)
+        else:
+            end_date = datetime.today() - relativedelta(years=75)
+            start_date = datetime.today() - relativedelta(years=100)
+            date = self.random_datetime(start_date, end_date)
+        return date
+
     def random_datetime(self, start: datetime, end: datetime) -> datetime:
         """
         Generate a random datetime between two datetime objects.