Updating markdown doc to address feedback comments (#84)

adrianoaru-nhs · web-flow · commit bfa4ed72b677 · 2025-05-28T10:01:02.000+01:00
## Description  Updating the markdown document as according to feedback comments. ## Context  Makes it easier to understand what the util does and how to use it. ## Type of changes  - [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  - [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 - [ ] 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.
diff --git a/docs/utility-guides/TableUtil.md b/docs/utility-guides/TableUtil.md
@@ -1,6 +1,7 @@
 # Utility Guide: Table Utility
 
-The Table Utilities module provides helper functions to interact with and validate HTML tables in Playwright-based UI tests.
+The Table Utilities module (`utils/table_util.py`) provides helper functions to interact with and validate HTML tables in Playwright-based UI tests.
+**This utility is designed to be used inside Page Object Model (POM) classes** to simplify table interactions and assertions.
 
 ## Table of Contents
 
@@ -9,227 +10,193 @@ The Table Utilities module provides helper functions to interact with and valida
   - [Using the Table Utility](#using-the-table-utility)
   - [Example usage](#example-usage)
     - [Get Column Index](#get-column-index)
-      - [Required Arguments](#required-arguments)
-      - [How This Function Works](#how-this-function-works)
+      - [Example](#example)
     - [Click First Link In Column](#click-first-link-in-column)
-      - [Required Arguments](#required-arguments-1)
-      - [How This Function Works](#how-this-function-works-1)
+      - [Example](#example-1)
     - [Click First Input In Column](#click-first-input-in-column)
-      - [Required Arguments](#required-arguments-2)
-      - [How This Function Works](#how-this-function-works-2)
+      - [Example](#example-2)
     - [Format Inner Text](#format-inner-text)
-      - [Required Arguments](#required-arguments-3)
-      - [How This Function Works](#how-this-function-works-3)
+      - [Example](#example-3)
     - [Get Table Headers](#get-table-headers)
-      - [Required Arguments](#required-arguments-4)
-      - [How This Function Works](#how-this-function-works-4)
+      - [Example](#example-4)
     - [Get Row Count](#get-row-count)
-      - [Required Arguments](#required-arguments-5)
-      - [How This Function Works](#how-this-function-works-5)
+      - [Example](#example-5)
     - [Pick Row](#pick-row)
-      - [Required Arguments](#required-arguments-6)
-      - [How This Function Works](#how-this-function-works-6)
+      - [Example](#example-6)
     - [Pick Random Row](#pick-random-row)
-      - [Required Arguments](#required-arguments-7)
-      - [How This Function Works](#how-this-function-works-7)
+      - [Example](#example-7)
     - [Pick Random Row Number](#pick-random-row-number)
-      - [Required Arguments](#required-arguments-8)
-      - [How This Function Works](#how-this-function-works-8)
+      - [Example](#example-8)
     - [Get Row Data With Headers](#get-row-data-with-headers)
-      - [Required Arguments](#required-arguments-9)
-      - [How This Function Works](#how-this-function-works-9)
+      - [Example](#example-9)
     - [Get Full Table With Headers](#get-full-table-with-headers)
-      - [Required Arguments](#required-arguments-10)
-      - [How This Function Works](#how-this-function-works-10)
+      - [Example](#example-10)
 
 ## Using the Table Utility
 
-To use the Table Utility, import the `TableUtils` class into your POM file and then define the actions using the its methods as needed.
+To use the Table Utility, import the `TableUtils` class into your Page Object Model (POM) file and instantiate it for each table you want to interact with.
 
-## Example usage
-
-Below is an example of how the TableUtils used in reports_page.py
+```python
+from utils.table_util import TableUtils
 
-    from utils.table_util import TableUtils
-    class ReportsPage(BasePage):
+class ReportsPage(BasePage):
     """Reports Page locators, and methods for interacting with the page."""
 
-      def __init__(self, page):
+    def __init__(self, page):
         super().__init__(page)
         self.page = page
 
-        # Initialize TableUtils for different tables
-        self.failsafe_reports_sub_links_table = TableUtils(page, "#listReportDataTable")
-        self.fail_safe_reports_screening_subjects_with_inactive_open_episodes_table = (
-            TableUtils(page, "#subjInactiveOpenEpisodes")
-        )
-      def click_failsafe_reports_sub_links(self):
-        """Clicks the first NHS number link from the primary report table."""
-        self.failsafe_reports_sub_links_table.click_first_link_in_column("NHS Number")
+        # Initialize TableUtils for different tables by passing the page and table selector
+        self.reports_table = TableUtils(page, "#listReportDataTable")
+        self.subjects_table = TableUtils(page, "#subjInactiveOpenEpisodes")
+```
 
-### Get Column Index
+## Example usage
 
-This function returns the index (1-based) of a specified column name. 1-based indexing means the first column is considered index 1 (not 0 as in Python lists).
-If the column is not found, the function returns -1.
+Below are examples of how to use `TableUtils` methods inside your POM methods or tests:
 
-#### Required Arguments
+```python
+# Click the first NHS number link in the reports table
+self.reports_table.click_first_link_in_column("NHS Number")
 
-- `column_name`:
-  - Type: `str`
-  - The visible header text of the column to locate.
+# Get the index of the "Status" column
+status_col_index = self.reports_table.get_column_index("Status")
 
-#### How This Function Works
+# Click the first checkbox in the "Select" column
+self.subjects_table.click_first_input_in_column("Select")
 
-1. Attempts to identify table headers from <thead> or <tbody>.
-2. Iterates through header cells and matches text with `column_name`.
-3. Returns the index if found, otherwise raises an error.
+# Get all table headers as a dictionary
+headers = self.reports_table.get_table_headers()
 
-### Click First Link In Column
+# Get the number of visible rows in the table
+row_count = self.reports_table.get_row_count()
 
-Clicks on the first hyperlink present in a specified column.
+# Pick a specific row (e.g., row 2)
+row_locator = self.reports_table.pick_row(2)
 
-#### Required Arguments
+# Pick a random row and click a link in the "Details" column
+random_row = self.reports_table.pick_random_row()
+random_row.locator("td").nth(self.reports_table.get_column_index("Details") - 1).locator("a").click()
 
-- `column_name`:
-  - Type: `str`
-  - The column in which the link needs to be found.
+# Get data for a specific row as a header-value dictionary
+row_data = self.reports_table.get_row_data_with_headers(1)
 
-#### How This Function Works
+# Get the entire table as a dictionary of rows
+full_table = self.reports_table.get_full_table_with_headers()
+```
 
-1. Finds the index of the specified column.
-2. Searches the first visible row in the column for an `<a>` tag.
-3. Clicks the first available link found.
+---
 
-### Click First Input In Column
+### Get Column Index
 
-Clicks on the first input element (e.g., checkbox/radio) in a specific column.
+Returns the index (1-based) of a specified column name. Returns -1 if not found.
 
-#### Required Arguments
+#### Example
 
-- `column_name`:
-  - Type: `str`
-  - The name of the column containing the input element.
+```python
+col_index = self.reports_table.get_column_index("Date")
+```
 
-#### How This Function Works
+### Click First Link In Column
 
-1. Locates the index of the specified column.
-2. Checks the first visible row for an `<input>` tag in that column.
-3. Clicks the first input found.
+Clicks on the first hyperlink present in a specified column.
 
-### Format Inner Text
+#### Example
 
-Formats inner text of a row string into a dictionary.
+```python
+self.reports_table.click_first_link_in_column("NHS Number")
+```
 
-#### Required Arguments
+### Click First Input In Column
 
-- data:
-  - Type: `str`
-  - Raw inner text of a table row (tab-delimited).
+Clicks on the first input element (e.g., checkbox/radio) in a specific column.
 
-#### How This Function Works
+#### Example
 
-1. Splits the string by tab characters (\t).
-2. Enumerates the result and maps index to cell value.
-3. Returns a dictionary representing the row.
+```python
+self.reports_table.click_first_input_in_column("Select")
+```
 
-### Get Table Headers
+### Format Inner Text
 
-Extracts and returns table headers.
+Formats inner text of a row string into a dictionary.
 
-#### Required Arguments
+#### Example
 
-- None
+```python
+row_dict = self.reports_table.format_inner_text("123\tJohn Doe\tActive")
+```
 
-#### How This Function Works
+### Get Table Headers
 
-1. Selects the first row inside <thead> (if available).
-2. Captures the visible text of each <th>.
-3. Returns a dictionary mapping index to header text.
+Extracts and returns table headers as a dictionary.
 
-### Get Row Count
+#### Example
 
-Returns the count of visible rows in the table.
+```python
+headers = self.reports_table.get_table_headers()
+```
 
-#### Required Arguments
+### Get Row Count
 
-- None
+Returns the count of visible rows in the table.
 
-#### How This Function Works
+#### Example
 
-1. Locates all <tr> elements inside <tbody>.
-2. Filters to include only visible rows.
-3. Returns the total count.
+```python
+count = self.reports_table.get_row_count()
+```
 
 ### Pick Row
 
-Returns a locator for a specific row.
-
-#### Required Arguments
+Returns a locator for a specific row (1-based).
 
-- `row_number`:
-  - Type: `int`
-  - The row index to locate (1-based).
+#### Example
 
-#### How This Function Works
-
-1. Builds a locator for the nth <tr> inside <tbody>.
-2. Returns the locator object.
+```python
+row_locator = self.reports_table.pick_row(3)
+```
 
 ### Pick Random Row
 
-Picks and returns a random row locator.
-
-#### Required Arguments
+Picks and returns a locator for a random visible row.
 
-- None
+#### Example
 
-#### How This Function Works
-
-1. Gets all visible rows inside <tbody>.
-2. Uses a secure random generator to pick one.
-3. Returns the locator for that row.
+```python
+random_row = self.reports_table.pick_random_row()
+```
 
 ### Pick Random Row Number
 
 Returns the number of a randomly selected row.
 
-#### Required Arguments
-
-- None
+#### Example
 
-#### How This Function Works
-
-1. Retrieves visible rows from <tbody>.
-2. Randomly selects an index using secrets.choice.
-3. Returns the numeric index.
+```python
+random_row_number = self.reports_table.pick_random_row_number()
+```
 
 ### Get Row Data With Headers
 
 Returns a dictionary of header-value pairs for a given row.
 
-#### Required Arguments
-
-- `row_number`:
-  - Type:int
-  - Index of the target row (1-based).
-
-#### How This Function Works
+#### Example
 
-1. Extracts text from the specified row.
-2. Retrieves headers using get_table_headers.
-3. Maps each cell to its respective header.
+```python
+row_data = self.reports_table.get_row_data_with_headers(2)
+```
 
 ### Get Full Table With Headers
 
 Constructs a dictionary of the entire table content.
 
-#### Required Arguments
+#### Example
 
-- None
+```python
+full_table = self.reports_table.get_full_table_with_headers()
+```
 
-#### How This Function Works
+---
 
-1. Gets all visible rows.
-2. Retrieves headers once.
-3. Loops over each row and builds a dictionary using get_row_data_with_headers.
-4. Returns a dictionary where each key is a row number.
+For more details on each function's implementation, refer to the source code in `utils/table_util.py`.
