Updating markdown doc to address feedback comments

Author: adrianoaru-nhs

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