Feature/bcss 20633 subject demographics util updates (#80)

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

<!-- Describe your changes in detail. -->
Updating the subject demographics util and markdown document to address
feedback given in reviews.

## Context

<!-- Why is this change required? What problem does it solve? -->
Allows for users to understand how to use the util easier by reading the
updated markdown document.
Also changed the util so that you can specify a specific DOB to update
the patient to.

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

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 date 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.