Added Investigation Dataset util guide and refactored a couple of docstrings

Author: Andyg79

docs/utility-guides/InvestigationDataset.md

@@ -0,0 +1,133 @@
+# Utility Guide: Investigation Dataset Utility
+
+The Investigation Dataset Utility provides methods to fill out the investigation dataset forms, and progress episodes, based on the age of the subject and the test results.
+
+## Table of Contents
+
+- [Utility Guide: Investigation Dataset Utility](#utility-guide-investigation-dataset-utility)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Investigation Dataset Utility](#using-the-investigation-dataset-utility)
+  - [Investigation Dataset Completion - Required Arguments](#investigation-dataset-completion---required-arguments)
+  - [After Investigation Dataset Complete - Required Arguments](#after-investigation-dataset-complete---required-arguments)
+  - [Investigation Dataset Specific Functions](#investigation-dataset-specific-functions)
+  - [Example Usage](#example-usage)
+
+## Using the Investigation Dataset Utility
+
+To use the Investigation Dataset Utility, import the `InvestigationDatasetCompletion` and/or `AfterInvestigationDatasetComplete` classes from the `utils.investigation_dataset` directory into your test file and call the relevant methods as required.
+
+## Investigation Dataset Completion - Required Arguments
+
+The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
+
+    Required arguments for initialization:
+        - page (Page): The Playwright Page object used for browser automation.
+
+    Required arguments for main method:
+        - nhs_no (str): The NHS number of the subject.
+        - result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
+
+## After Investigation Dataset Complete - Required Arguments
+
+The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
+
+    Required arguments for initialization:
+        - page (Page): The Playwright Page object used for browser automation.
+
+    Required arguments for main method:
+        - result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
+        - younger (bool): True if the subject is younger than 50, False otherwise.
+
+
+## Investigation Dataset Specific Functions
+
+The `investigation_dataset` utility is used to complete the investigation dataset forms for a subject.It contains methods to fill out the forms, and progress episodes, based on the age of the subject and the test result. Below are their key functions:
+
+1. **`complete_with_result(self, nhs_no: str, result: str) -> None`**
+    This method fills out the investigation dataset forms based on the test result and the subject's age.
+
+   - **Arguments**:
+    - nhs_no (str): The NHS number of the subject.
+    - result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
+
+1. **`go_to_investigation_datasets_page(self, nhs_no) -> None`**
+    This method navigates to the investigation datasets page for a subject.
+    
+   - **Arguments**:
+    - nhs_no (str): The NHS number of the subject.
+
+1. **`default_investigation_dataset_forms(self) -> None`**
+    This method fills out the first part of the default investigation dataset form.
+
+1. **`default_investigation_dataset_forms_continuation(self) -> None`**
+    This method fills out the second part of the default investigation dataset form.
+
+1. **`investigation_datasets_failure_reason(self) -> None`**
+    This method fills out the failure reason section of the investigation dataset form.
+
+1. **`polyps_for_high_risk_result(self) -> None`**
+    This method fills out the polyp information section of the investigation dataset form to trigger a high risk result.
+
+1. **`polyps_for_lnpcp_result(self) -> None`**
+    This method fills out the polyp information section of the investigation dataset form to trigger a LNPCP result.
+
+1. **`polyp1_intervention(self) -> None`**
+    This method fills out the intervention section of the investigation dataset form for polyp 1.
+
+1. **`save_investigation_dataset(self) -> None`**
+    This method saves the investigation dataset form.
+
+1. **`progress_episode_based_on_result(self, result: str, younger: bool) -> None`**
+    This method progresses the episode based on the result of the investigation dataset.
+   - **Arguments**:
+     - result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
+     - younger (bool): True if the subject is younger than 50, False otherwise.
+
+1. **`after_high_risk_result(self) -> None`**
+    This method advances an episode that has a high-risk result.
+
+1. **`after_lnpcp_result(self) -> None`**
+    This method advances an episode that has a LNPCP result.
+
+1. **`after_normal_result(self) -> None`**
+    This method advances an episode that has a normal result.
+
+1. **`handover_subject_to_symptomatic_care(self) -> None`**
+    This method hands over a subject to symptomatic care.
+
+1. **`record_diagnosis_date(self) -> None`**
+    This method records the diagnosis date for a subject.
+
+## Example Usage
+
+```python
+from playwright.sync_api import sync_playwright
+from utils.investigation_dataset import (
+    InvestigationDatasetCompletion,
+    InvestigationDatasetResults,
+    AfterInvestigationDatasetComplete,
+)
+
+def example_investigation_dataset_usage(nhs_no: str, result: str, younger: bool) -> None:
+    # Start Playwright and open a browser/page (simplified for example)
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        page = browser.new_page()
+
+        # Complete the investigation dataset for a subject
+        investigation = InvestigationDatasetCompletion(page)
+        investigation.complete_with_result(nhs_no, result)
+
+        # Progress the episode based on the result and subject's age
+        after_investigation = AfterInvestigationDatasetComplete(page)
+        after_investigation.progress_episode_based_on_result(result, younger)
+
+        browser.close()
+
+# Example usage:
+example_investigation_dataset_usage(
+    nhs_no="1234567890",
+    result=InvestigationDatasetResults.HIGH_RISK,
+    younger=True
+)
+```

tests/smokescreen/test_compartment_6.py

@@ -20,7 +20,7 @@ def test_compartment_6(page: Page) -> None:
     This is the main compartment 6 method
     This test fills out the investigation datasets for different subjects to get different outcomes for a diagnostic test
     based on the test results and the subject's age, then prints the diagnostic test result letters.
-    If the subject is old enough and they get a high-risk or LNPCP result, then they are handed over 
+    If the subject is old enough and they get a high-risk or LNPCP result, then they are handed over
     into symptomatic care, and the relevant letters are printed.
     """
 

utils/investigation_dataset.py

@@ -61,19 +61,28 @@ class InvestigationDatasetResults(StrEnum):
 class InvestigationDatasetCompletion:
     """
     This class is used to complete the investigation dataset forms for a subject.
-    It contains methods to fill out the forms based on the result of the investigation dataset.
+    It contains methods to fill out the forms, and progress episodes, based on the
+    age of the subject and the test result.
+
+    This class provides methods to:
+    - Navigate to the investigation datasets page for a subject.
+    - Fill out investigation dataset forms with default or result-specific data.
+    - Handle different investigation outcomes (e.g., HIGH_RISK, LNPCP, NORMAL) by populating relevant form fields and sections.
+    - Add and configure polyp information and interventions to trigger specific result scenarios.
+    - Save the completed investigation dataset.
     """
 
     def __init__(self, page: Page):
         self.page = page
         self.estimate_whole_polyp_size_string = "Estimate of whole polyp size"
         self.polyp_access_string = "Polyp Access"
 
-    def complete_with_result(self, nhs_no: str, result: str):
+    def complete_with_result(self, nhs_no: str, result: str) -> None:
         """This method fills out the investigation dataset forms based on the test result and the subject's age.
         Args:
             nhs_no (str): The NHS number of the subject.
             result (str): The result of the investigation dataset.
+                Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
         """
         if result == InvestigationDatasetResults.HIGH_RISK:
             self.go_to_investigation_datasets_page(nhs_no)
@@ -119,7 +128,7 @@ def go_to_investigation_datasets_page(self, nhs_no) -> None:
         SubjectDatasetsPage(self.page).click_investigation_show_datasets()
 
     def default_investigation_dataset_forms(self) -> None:
-        """This method fills out the first art of the default investigation dataset form."""
+        """This method fills out the first part of the default investigation dataset form."""
         # Investigation Dataset
         InvestigationDatasetsPage(self.page).select_site_lookup_option(
             SiteLookupOptions.RL401
@@ -200,7 +209,7 @@ def investigation_datasets_failure_reason(self) -> None:
         )
 
     def polyps_for_high_risk_result(self) -> None:
-        """This method fills out the polyp information section of the investigation dataset form o trigger a high risk result."""
+        """This method fills out the polyp information section of the investigation dataset form to trigger a high risk result."""
         # Polyp Information
         InvestigationDatasetsPage(self.page).click_add_polyp_button()
         DatasetFieldUtil(self.page).populate_select_locator_for_field_inside_div(
@@ -323,6 +332,7 @@ def progress_episode_based_on_result(self, result: str, younger: bool) -> None:
         """This method progresses the episode based on the result of the investigation dataset.
         Args:
             result (str): The result of the investigation dataset.
+                Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
             younger (bool): True if the subject is younger than 50, False otherwise.
         """
         if result == InvestigationDatasetResults.HIGH_RISK: