Responded to review comments and updated doc strings

Author: victor-soares-ibm

docs/utility-guides/ScreeningSubjectPageSearcher.md

@@ -2,18 +2,19 @@
 
 The Screening Subject Search utility allows for
 
-- searching for relevant subjects using their NHS Number, forename, last name, DOB, post code, episode closed date, status or latest event status
-- verifying the subject's event status using their nhs number
+- searching for relevant subjects using their NHS Number, forename, last name, DOB, postcode, episode closed date, status or latest event status
+- verifying the subject's event status using their NHS number
 
 ## Table of Contents
 
 - [Utility Guide: Screening Subject Page Searcher](#utility-guide-screening-subject-page-searcher)
   - [Table of Contents](#table-of-contents)
   - [Functions Overview](#functions-overview)
-    - [Verify subject event status by nhs no](#verify-subject-event-status-by-nhs-no)
+    - [The page object parameter:](#the-page-object-parameter)
+    - [Verify subject event status by NHS no](#verify-subject-event-status-by-nhs-no)
       - [Arguments](#arguments)
       - [How This Function Works](#how-this-function-works)
-    - [Search subject by nhs number](#search-subject-by-nhs-number)
+    - [Search subject by NHS number](#search-subject-by-nhs-number)
       - [Arguments](#arguments-1)
       - [How This Function Works](#how-this-function-works-1)
     - [Search subject by surname](#search-subject-by-surname)
@@ -25,7 +26,7 @@ The Screening Subject Search utility allows for
     - [Search subject by date of birth](#search-subject-by-date-of-birth)
       - [Arguments](#arguments-4)
       - [How This Function Works](#how-this-function-works-4)
-    - [Search subject by post code](#search-subject-by-post-code)
+    - [Search subject by postcode](#search-subject-by-postcode)
       - [Arguments](#arguments-5)
       - [How This Function Works](#how-this-function-works-5)
     - [Search subject by episode closed date](#search-subject-by-episode-closed-date)
@@ -61,10 +62,13 @@ For this utility we have the following functions:
 - `search_subject_by_search_area`
 - `check_clear_filters_button_works`
 
-### Verify subject event status by nhs no
+### The page object parameter:
+- is required for all the listed functions above. It is listed as an arguement just once to avoid repetition
+
+### Verify subject event status by NHS no
 
 This is used to check that the latest event status of a subject has been updated to what is expected.
-The provided nhs no is used to search the whole database and then verifies the latest event status is as expected.
+The provided NHS no is used to search the whole database and then verifies the latest event status is as expected.
 
 #### Arguments
 
@@ -73,7 +77,7 @@ The provided nhs no is used to search the whole database and then verifies the l
   - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `nhs_no`:
   - Type: `str`
-  - This is the subject's nhs number. For example: 123 456 7890
+  - This is the subject's NHS number. For example: 123 456 7890
 - `latest_event_status`:
   - Type: `str`
   - This is the expected status of the subject that is being verified
@@ -82,37 +86,31 @@ The provided nhs no is used to search the whole database and then verifies the l
 
 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 screening subject search page
-3. From here it fills in the nhs number filter field with the supplied nhs number and chooses the whole area database as the search area option
+3. From here it fills in the NHS number filter field with the supplied NHS number and chooses the whole area database as the search area option
 4. It then clicks the search button
 5. Once the subject is returned, it then verifies that the latest event status matches the supplied event status
 
-### Search subject by nhs number
+### Search subject by NHS number
 
 This searches for a subject by their NHS Number
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `nhs_no`:
   - Type: `str`
-  - This is the subject's nhs number. For example: 123 456 7890
+  - This is the subject's NHS number. For example: 123 456 7890
 
 #### How This Function Works
 
 1. It starts off by clicking on the **Clear filters** button to remove any persisting filters
-2. It then fills in the nhs number filter field with the supplied nhs number and clicks the search button
+2. It then fills in the NHS number filter field with the supplied NHS number and clicks the search button
 
 ### Search subject by surname
 
 This searches for a subject by their surname
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `surname`:
   - Type: `str`
   - This is the subject's surname
@@ -128,9 +126,6 @@ This searches for a subject by their forename
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `forename`:
   - Type: `str`
   - This is the subject's forename
@@ -146,9 +141,6 @@ This searches for a subject by their date of birth
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `dob`:
   - Type: `str`
   - This is the subject's date of birth
@@ -158,33 +150,27 @@ This searches for a subject by their date of birth
 1. It starts off by clicking on the **Clear filters** button to remove any persisting filters
 2. It then fills in the date of birth filter field with the supplied DOB and clicks the search button
 
-### Search subject by post code
+### Search subject by postcode
 
-This searches for a subject by their post code
+This searches for a subject by their postcode
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `postcode`:
   - Type: `str`
-  - This is the subject's post code
+  - This is the subject's postcode
 
 #### How This Function Works
 
 1. It starts off by clicking on the **Clear filters** button to remove any persisting filters
-2. It then fills in the post code filter field with the supplied post code and clicks the search button
+2. It then fills in the postcode filter field with the supplied postcode and clicks the search button
 
 ### Search subject by episode closed date
 
 This searches for a subject by their episode closed date
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `episode_closed_date`:
   - Type: `str`
   - This is the subject's episode closed date
@@ -200,9 +186,6 @@ This searches for a subject by their screening status
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `status`:
   - Type: `str`
   - This is the subject's screening status
@@ -218,9 +201,6 @@ This searches for a subject by their latest event status
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `status`:
   - Type: `str`
   - This is the subject's latest event status
@@ -236,9 +216,6 @@ This searches for a subject by search area
 
 #### Required Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `status`:
   - Type: `str`
   - This is the subject's screening status
@@ -267,14 +244,11 @@ This checks that the "clear filter" button works as intended
 
 #### Arguments
 
-- `page`:
-  - Type: `Page`
-  - This is the playwright page object which is used to tell playwright what page the test is currently on
 - `nhs_no`:
   - Type: `str`
-  - This is the subject's nhs number. For example: 123 456 7890
+  - This is the subject's NHS number. For example: 123 456 7890
 
 #### How This Function Works
 
-1. It fills in the nhs number filter field with the supplied nhs number and verifies that the nhs number filter field contains the entered value
-2. It then clicks the clear filters button and verifies that the nhs number filter field is now empty
+1. It fills in the NHS number filter field with the supplied NHS number and verifies that the NHS number filter field contains the entered value
+2. It then clicks the clear filters button and verifies that the NHS number filter field is now empty

utils/screening_subject_page_searcher.py

@@ -16,6 +16,11 @@ def verify_subject_event_status_by_nhs_no(
     This is used to check that the latest event status of a subject has been updated to what is expected
     We provide the NHS Number for the subject and the expected latest event status and it navigates to the correct page
     From here it searches for that subject against the whole database and verifies the latest event status is as expected
+
+    Args:
+        page (Page): This is the playwright page object
+        nhs_no (str): The screening subject's nhs number
+        latest_event_status (str | list): the screening subjects's latest event status
     """
     BasePage(page).click_main_menu_link()
     BasePage(page).go_to_screening_subject_search_page()
@@ -33,79 +38,111 @@ def verify_subject_event_status_by_nhs_no(
     )
 
 
-def search_subject_by_nhs_number(page: Page, nhs_number) -> None:
+def search_subject_by_nhs_number(page: Page, nhs_number: str) -> None:
     """
     This searches for a subject by their NHS Number and checks the page has redirected accordingly
+
+    Args:
+        page (Page): This is the playwright page object
+        nhs_no (str): The screening subject's nhs number
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).nhs_number_filter.fill(nhs_number)
     SubjectScreeningPage(page).nhs_number_filter.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_surname(page: Page, surname) -> None:
+def search_subject_by_surname(page: Page, surname: str) -> None:
     """
     This searches for a subject by their surname and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        surname (str): The screening subject's surname
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).surname_filter.fill(surname)
     SubjectScreeningPage(page).surname_filter.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_forename(page: Page, forename) -> None:
+def search_subject_by_forename(page: Page, forename: str) -> None:
     """
     This searches for a subject by their forename and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        forename (str): The screening subject's forename
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).forename_filter.fill(forename)
     SubjectScreeningPage(page).forename_filter.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_dob(page: Page, dob) -> None:
+def search_subject_by_dob(page: Page, dob: str) -> None:
     """
     This searches for a subject by their date of birth and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        dob (str): The screening subject's date of birth
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).date_of_birth_filter.fill(dob)
     SubjectScreeningPage(page).date_of_birth_filter.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_postcode(page: Page, postcode) -> None:
+def search_subject_by_postcode(page: Page, postcode: str) -> None:
     """
     This searches for a subject by their postcode and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        postcode (str): The screening subject's postcode
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).postcode_filter.fill(postcode)
     SubjectScreeningPage(page).postcode_filter.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_episode_closed_date(page: Page, episode_closed_date) -> None:
+def search_subject_by_episode_closed_date(page: Page, episode_closed_date: str) -> None:
     """
     This searches for a subject by their episode closed date and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        episode_closed_date (str): The screening subject's episode closed date
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).episode_closed_date_filter.fill(episode_closed_date)
     SubjectScreeningPage(page).episode_closed_date_filter.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_status(page: Page, status) -> None:
+def search_subject_by_status(page: Page, status: str) -> None:
     """
     This searches for a subject by their screening status and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        status (str): The screening subject's screening status
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).select_screening_status_options(status)
     SubjectScreeningPage(page).select_screening_status.press("Tab")
     SubjectScreeningPage(page).click_search_button()
 
 
-def search_subject_by_latest_event_status(page: Page, status) -> None:
+def search_subject_by_latest_event_status(page: Page, status: str) -> None:
     """
     This searches for a subject by their latest event status and checks the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        status (str): The screening subject's latest event status
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).select_episode_status_option(status)
@@ -114,10 +151,17 @@ def search_subject_by_latest_event_status(page: Page, status) -> None:
 
 
 def search_subject_by_search_area(
-    page: Page, status, search_area, code=None, gp_practice_code=None
+    page: Page, status: str, search_area: str, code: str=None, gp_practice_code: str=None
 ) -> None:
     """
     This searches for a subject by the search area, populating necessary fields were needed, and checks that the page has redirected accordingly
+    
+    Args:
+        page (Page): This is the playwright page object
+        status (str): The screening subject's screening status
+        search_area (str): This is the search area option to use
+        code (str): If provided, the code parameter is used to fill the appropriate code filter field
+        gp_practice_code (str): If provided, the GP practice code parameter is used to fill the GP Practice in CCG filter field
     """
     SubjectScreeningPage(page).click_clear_filters_button()
     SubjectScreeningPage(page).select_screening_status_options(status)
@@ -133,9 +177,13 @@ def search_subject_by_search_area(
     SubjectScreeningPage(page).click_search_button()
 
 
-def check_clear_filters_button_works(page, nhs_number) -> None:
+def check_clear_filters_button_works(page: Page, nhs_number: str) -> None:
     """
     This checks that the "clear filter" button works as intended
+    
+    Args:
+        page (Page): This is the playwright page object
+        nhs_number (str): The screening subject's nhs number
     """
     SubjectScreeningPage(page).nhs_number_filter.fill(nhs_number)
     expect(SubjectScreeningPage(page).nhs_number_filter).to_have_value(nhs_number)