Feature/bcss 20327 compartment 5 utils (#46)

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

<!-- Describe your changes in detail. -->
Adding Utils for compartment 5
Altering the calendar picker util to use the date time utils and work
for more dates
Added markdown documents for two utils

## Context

<!-- Why is this change required? What problem does it solve? -->
Allows compartment 5 to retrieve subjects from the DB
Increases reliability of the calendar utils

## 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)
- [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/BatchProcessing.md

@@ -0,0 +1,118 @@
+# Utility Guide: Batch Processing
+
+The Batch Processing utility allows for the processing of batches on the active batch list page to be completed in one method
+
+## Table of Contents
+
+- [Utility Guide: Batch Processing](#utility-guide-batch-processing)
+  - [Table of Contents](#table-of-contents)
+  - [Functions Overview](#functions-overview)
+    - [Batch Processing](#batch-processing)
+      - [Required Arguments](#required-arguments)
+      - [Optional Arguments](#optional-arguments)
+      - [How This Function Works](#how-this-function-works)
+    - [Prepare And Print Batch](#prepare-and-print-batch)
+      - [Arguments](#arguments)
+      - [How This Function Works](#how-this-function-works-1)
+    - [Check Batch In Archived Batch List](#check-batch-in-archived-batch-list)
+      - [Arguments](#arguments-1)
+      - [How This Function Works](#how-this-function-works-2)
+
+## Functions Overview
+
+For this utility we have the following functions:
+
+- `batch_processing`
+- `prepare_and_print_batch`
+- `check_batch_in_archived_batch_list`
+
+### Batch Processing
+
+This is the main function that is called in order to process a batch.
+This will call the other two functions in order to successfully process a batch.
+
+#### Required Arguments
+
+- `page`:
+  - Type: `Page`
+  - This is the playwright page object which is used to tell playwright what page the test is currently on.
+- `batch_type`:
+  - Type: `str`
+  - This is the event code for the batch. For example: **S1** or **A323**
+- `batch_description`:
+  - Type: `str`
+  - This is the description of the batch. For example: **Pre-invitation (FIT)** or **Post-investigation Appointment NOT Required**
+- `latest_event_status`:
+  - Type: `str`
+  - This is the status the subject will get updated to after the batch has been processed. It is used to check that the subject has been updated to the correct status after a batch has been printed
+
+#### Optional Arguments
+
+- `run_timed_events`:
+  - Type: `bool`
+  - If this is set to **True**, then bcss_timed_events will be executed against all the subjects found in the batch
+- `get_subjects_from_pdf`:
+  - Type: `bool`
+  - If this is set to **True**, then the subjects will be retrieved from the downloaded PDF file instead of from the DB
+
+#### How This Function Works
+
+1. It starts off by navigating to the main menu if not already on this page. This is done to ensure that this can be called from any page
+2. Once on the main menu it navigates to the active batch list
+3. From here it fills in the search filters to narrow down the list of active batches to only those which match the arguments provided
+4. Once only the expected batches are shown it checks the status column of the records
+   1. If *Prepared* is found then it ignores it, otherwise if *Open* is found then it carries on
+5. Now it extracts the ID of the batch and stores it in the local variable `link_text`, this is used later on to extracts the subjects in the batch from the DB
+6. After the ID is stored, it clicks on the ID to get to the Manage Active Batch page
+7. From Here it calls the `prepare_and_print_batch` function.
+   1. If `get_subjects_from_pdf` was set to False it calls `get_nhs_no_from_batch_id`, which is imported from *utils.oracle.oracle_specific_functions*, to get the subjects from the batch and stores them as a pandas DataFrame - **nhs_no_df**
+   2. For more Info on `get_nhs_no_from_batch_id` please look at: [`PDFReader`](PDFReader.md)
+8. Once this is complete it calls the `check_batch_in_archived_batch_list` function
+9. Finally, once that function is complete it calls `verify_subject_event_status_by_nhs_no` which is imported from *utils/screening_subject_page_searcher*
+
+### Prepare And Print Batch
+
+This is used when on the Manage Active Batch page.
+It is in charge of pressing on the following button: **Prepare Batch**, **Retrieve** and **Confirm Printed**
+
+#### Arguments
+
+- `page`:
+  - Type: `Page`
+  - This is the playwright page object which is used to tell playwright what page the test is currently on.
+- `link_text`:
+  - Type: `str`
+  - This is the batch ID of the batch currently being processed
+- `get_subjects_from_pdf`:
+  - Type: `bool`
+  - This is an optional argument and if this is set to **True**, then the subjects will be retrieved from the downloaded PDF file instead of from the DB
+
+#### How This Function Works
+
+1. It starts off by clicking on the **Prepare Batch** button.
+2. After this it waits for the button to turn into **Re-Prepare Batch**. Once this happens it means that the batch is ready to be printed.
+3. Now It clicks on each **Retrieve** button visible.
+   1. If `get_subjects_from_pdf` was set to True and the file is a **.pdf**, then it calls `extract_nhs_no_from_pdf`, which is imported from *utils/pdf_reader*, to get the subjects from the batch and stores them as a pandas DataFrame - **nhs_no_df**
+   2. After a file is downloaded, it gets deleted.
+4. Then it clicks on each **Confirm Printed** button ensuring to handle the dialog that appears.
+5. Finally it checks for the message: *Batch Successfully Archived and Printed*
+
+### Check Batch In Archived Batch List
+
+This function checks that the batch that was just prepared and printed is now visible in the archived batch list
+
+#### Arguments
+
+- `page`:
+  - Type: `Page`
+  - This is the playwright page object which is used to tell playwright what page the test is currently on.
+- `link_text`:
+  - Type: `str`
+  - This is the batch ID of the batch currently being processed
+
+#### How This Function Works
+
+1. This starts off by navigating to the main menu.
+2. From here it goes to the archived batch list page.
+3. Once on the archived batch list page, it enters `link_text` into the ID filter.
+4. Finally it checks that the batch is visible in the table.

docs/utility-guides/PDFReader.md

@@ -0,0 +1,35 @@
+# Utility Guide: PDF Reader
+
+The PDF Reader utility allows for reading of PDF files and performing specific tasks on them.
+
+## Table of Contents
+
+- [Utility Guide: PDF Reader](#utility-guide-pdf-reader)
+  - [Table of Contents](#table-of-contents)
+  - [Functions Overview](#functions-overview)
+    - [Extract NHS No From PDF](#extract-nhs-no-from-pdf)
+      - [Required Arguments](#required-arguments)
+      - [How This Function Works](#how-this-function-works)
+
+## Functions Overview
+
+For this utility we have the following functions/methods:
+
+- `extract_nhs_no_from_pdf`
+
+### Extract NHS No From PDF
+
+This is called to extract all NHS numbers from a PDF file.
+The way it finds an NHS number is by looking for the string **"NHS No:"**
+
+#### Required Arguments
+
+- `file`:
+  - Type: `str`
+  - This is the file path stored as a string.
+
+#### How This Function Works
+
+1. It starts off by storing the PDF file as a PdfReader object, this is from the `pypdf` package.
+2. Then it loops through each page.
+3. If it finds the string *"NHS No"* in the page, it extracts it and removes any whitespaces, then adds it to a pandas DataFrame - `nhs_no_df`

pages/communication_production/batch_list_page.py

@@ -28,6 +28,9 @@ def __init__(self, page: Page):
         self.deadline_date_filter = self.page.get_by_role("cell", name="").get_by_role(
             "textbox"
         )
+        self.deadline_date_filter_with_input = self.page.locator(
+            "input.form-control.filter.filtering"
+        )
         self.deadline_date_clear_button = self.page.get_by_role("cell", name="Clear")
 
     def verify_batch_list_page_title(self, text) -> None:
@@ -88,6 +91,9 @@ def clear_deadline_filter_date(self) -> None:
         self.click(self.deadline_calendar_picker)
         self.click(self.deadline_date_clear_button)
 
+    def verify_deadline_date_filter_input(self, expected_text: str) -> None:
+        expect(self.deadline_date_filter_with_input).to_have_value(expected_text)
+
 
 class ActiveBatchListPage(BatchListPage):
     """Active Batch List Page locators, and methods for interacting with the Active Batch List page"""

pages/screening_practitioner_appointments/screening_practitioner_day_view_page.py

@@ -10,6 +10,7 @@ def __init__(self, page: Page):
         self.page = page
         # Screening Practitioner Day View   - page locators
         self.calendar_button = page.get_by_role("button", name="Calendar")
+        self.practitioner_dropdown = self.page.locator("#UI_PRACTITIONER_NDV")
 
     def click_calendar_button(self) -> None:
         """Click on the Calendar button to open the calendar picker."""
@@ -18,3 +19,7 @@ def click_calendar_button(self) -> None:
     def click_patient_link(self, patient_name: str) -> None:
         """Click on the patient link to navigate to the patient's details page."""
         self.click(self.page.get_by_role("link", name=patient_name))
+
+    def select_practitioner_dropdown_option(self, practitioner: str | list) -> None:
+        """Select given practitioner from the practitioner dropdown list"""
+        self.practitioner_dropdown.select_option(label=practitioner)

pages/screening_subject_search/advance_fobt_screening_episode_page.py

@@ -1,5 +1,7 @@
 from playwright.sync_api import Page, expect, Locator
 from pages.base_page import BasePage
+import logging
+import pytest
 
 
 class AdvanceFOBTScreeningEpisodePage(BasePage):
@@ -62,11 +64,16 @@ def get_latest_event_status_cell(self, latest_event_status: str) -> Locator:
         return self.page.get_by_role("cell", name=latest_event_status, exact=True)
 
     def verify_latest_event_status_value(self, latest_event_status: str) -> None:
-        """Verify the latest event status value."""
+        """Verify that the latest event status value is visible."""
+        logging.info(f"Verifying subject has the status: {latest_event_status}")
         latest_event_status_cell = self.get_latest_event_status_cell(
             latest_event_status
         )
-        expect(latest_event_status_cell).to_be_visible()
+        try:
+            expect(latest_event_status_cell).to_be_visible()
+            logging.info(f"Subject has the status: {latest_event_status}")
+        except Exception:
+            pytest.fail(f"Subject does not have the status: {latest_event_status}")
 
     def click_record_other_post_investigation_contact_button(self) -> None:
         """Click the 'Record other post-investigation contact' button."""

pages/screening_subject_search/subject_screening_search_page.py

@@ -1,4 +1,4 @@
-from playwright.sync_api import Page
+from playwright.sync_api import Page, expect
 from pages.base_page import BasePage
 from enum import Enum
 from utils.calendar_picker import CalendarPicker
@@ -148,6 +148,9 @@ def select_dob_using_calendar_picker(self, date) -> None:
         self.click(self.dob_calendar_picker)
         CalendarPicker(self.page).v1_calender_picker(date)
 
+    def verify_date_of_birth_filter_input(self, expected_text: str) -> None:
+        expect(self.date_of_birth_filter).to_have_value(expected_text)
+
 
 class ScreeningStatusSearchOptions(Enum):
     """Enum for Screening Status Search Options"""

pages/screening_subject_search/subject_screening_summary_page.py

@@ -1,6 +1,8 @@
 from playwright.sync_api import Page, expect, Locator
 from pages.base_page import BasePage
 from enum import Enum
+import logging
+import pytest
 
 
 class SubjectScreeningSummaryPage(BasePage):
@@ -84,10 +86,15 @@ def verify_latest_event_status_header(self) -> None:
 
     def verify_latest_event_status_value(self, latest_event_status: str) -> None:
         """Verify that the latest event status value is visible."""
+        logging.info(f"Verifying subject has the status: {latest_event_status}")
         latest_event_status_cell = self.get_latest_event_status_cell(
             latest_event_status
         )
-        expect(latest_event_status_cell).to_be_visible()
+        try:
+            expect(latest_event_status_cell).to_be_visible()
+            logging.info(f"Subject has the status: {latest_event_status}")
+        except Exception:
+            pytest.fail(f"Subject does not have the status: {latest_event_status}")
 
     def click_subjects_events_notes(self) -> None:
         """Click on the 'Subject Events & Notes' link."""
@@ -155,7 +162,12 @@ def click_datasets_link(self) -> None:
 
     def click_advance_fobt_screening_episode_button(self) -> None:
         """Click on the 'Advance FOBT Screening Episode' button."""
-        self.click(self.advance_fobt_screening_episode_button)
+        logging.info("Advancing the episode")
+        try:
+            self.click(self.advance_fobt_screening_episode_button)
+            logging.info("Episode successfully advanced")
+        except Exception as e:
+            pytest.fail(f"Unable to advance the episode: {e}")
 
 
 class ChangeScreeningStatusOptions(Enum):

tests/smokescreen/bcss_smokescreen_tests.properties

@@ -85,12 +85,12 @@
 # ----------------------------------
 #   compartment 5
 # ----------------------------------
-#    c5_eng_number_of_screening_appts_to_attend=5
+    c5_eng_number_of_screening_appts_to_attend=5
 
 # ----------------------------------
 #   compartment 6
 # ----------------------------------
-#    c6_eng_number_of_normal_results_to_record=2
+#    c6_eng_number_of_normal_results_to_record=1
 #    c6_eng_number_of_lnpcp_results_to_record=1
 #    c6_eng_number_of_high_risk_findings_results_to_record=1
 #    c6_eng_number_of_lnpcp_results_over_74_to_record=1

tests/smokescreen/test_compartment_2.py

@@ -56,15 +56,9 @@ def test_compartment_2(page: Page, smokescreen_properties: dict) -> None:
             pytest.fail(f"{fit_device_id} unsuccessfully logged: {str(e)}")
 
     nhs_no = subjectdf["subject_nhs_number"].iloc[0]
-    try:
-        verify_subject_event_status_by_nhs_no(
-            page, nhs_no, "S43 - Kit Returned and Logged (Initial Test)"
-        )
-        logging.info(
-            f"Successfully verified NHS number {nhs_no} with status S43 - Kit Returned and Logged (Initial Test)"
-        )
-    except Exception as e:
-        pytest.fail(f"Verification failed for NHS number {nhs_no}: {str(e)}")
+    verify_subject_event_status_by_nhs_no(
+        page, nhs_no, "S43 - Kit Returned and Logged (Initial Test)"
+    )
 
     BasePage(page).click_main_menu_link()
     BasePage(page).go_to_fit_test_kits_page()

tests/smokescreen/test_compartment_3.py

@@ -66,16 +66,7 @@ def test_compartment_3(page: Page, smokescreen_properties: dict) -> None:
             f"Verifying NHS number: {nhs_number} with expected status: {expected_status}"
         )
 
-        try:
-            verify_subject_event_status_by_nhs_no(page, nhs_number, expected_status)
-            logging.info(
-                f"Successfully verified NHS number {nhs_number} with status {expected_status}"
-            )
-        except Exception as e:
-            logging.error(
-                f"Verification failed for NHS number {nhs_number} with status {expected_status}: {str(e)}"
-            )
-            raise
+        verify_subject_event_status_by_nhs_no(page, nhs_number, expected_status)
 
     # Process S2 batch
     batch_processing(