Feature/bcss 20022 add a table utility (#23)

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

<!-- Describe your changes in detail. -->

## Context
This PR is adding a new table util to be able to use for all tables on
BCSS.
Currently test_report page using the first two methods of table util to
click on first link in the table and
Reports.page is the place where the locators of the table are stored

<!-- Why is this change required? What problem does it solve? -->

## Type of changes
This was added so that we could have a general utility to call whenever
we need to use a table during our automated tests.

<!-- 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
- [ ] I have added tests to cover my changes (where appropriate)
- [ ] 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: mepr1

pages/reports/reports_page.py

@@ -1,12 +1,17 @@
 from playwright.sync_api import Page
 from pages.base_page import BasePage
+from utils.table_util import TableUtils
 
 
 class ReportsPage(BasePage):
     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")
+
         # Reports page main menu links
         self.bureau_reports_link = self.page.get_by_text("Bureau Reports")
         self.failsafe_reports_link = self.page.get_by_role(
@@ -179,32 +184,22 @@ def go_to_screening_practitioner_6_weeks_availability_not_set_up_report_page(
         )
 
     def go_to_screening_practitioner_appointments_page(self) -> None:
-        self.click(self.screening_practitioner_appointments_link)
+        self.click(self.screening_practitioner_appointments_page)
+
+    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")
+
+    def click_fail_safe_reports_screening_subjects_with_inactive_open_episodes_link(self):
+        """
+        Clicks the first NHS number link from the primary report table.
+        """
+        self.fail_safe_reports_screening_subjects_with_inactive_open_episodes_table.click_first_link_in_column("NHS Number")
 
-    def click_nhs_number_link(self, page: Page) -> None:
+    def click_fail_safe_reports_identify_and_link_new_gp_practices_link(self):
         """
-        Clicks the first NHS number link present on the screen if any are found.
+        Clicks the first Practice Code link from the primary report table.
         """
-        # List of locators to check for NHS number links.
-        # This implementation is a workaround for the fact that the NHS number
-        # links are not using the same locators accross bcss
-        # This is a temporary solution until
-        # we have a table utility that will allow us to interact with tables across bcss.
-        locators = [
-            "#listReportDataTable > tbody > tr:nth-child(3) > td:nth-child(1) > a",
-            "//*[@id='listReportDataTable']/tbody/tr[3]/td[1]",
-            "//*[@id='listReportDataTable']/tbody/tr[3]/td[2]",
-            "#listReportDataTable > tbody > tr:nth-child(3) > td:nth-child(1) > a",
-            "#subjInactiveOpenEpisodes > tbody > tr:nth-child(1) > td.NHS_NUMBER.dt-type-numeric > a",
-        ]
-
-        for locator_string in locators:
-            try:
-                # Use page.locator to get a locator object
-                locator = page.locator(locator_string)
-                # Check if the locator is visible
-                if locator.is_visible():
-                    # Click the locator
-                    locator.click()
-            except Exception:
-                print("No NHS number links found on the page")
+        self.failsafe_reports_sub_links_table.click_first_link_in_column("Practice Code")

tests/test_reports_page.py

@@ -25,7 +25,7 @@ def before_each(page: Page):
     BasePage(page).go_to_reports_page()
 
 
-@pytest.mark.smoke
+
 def test_reports_page_navigation(page: Page) -> None:
     """
     Confirms all menu items are displayed on the reports page, and that the relevant pages
@@ -131,14 +131,13 @@ def test_failsafe_reports_screening_subjects_with_inactive_open_episode(
     ReportsPage(page).click_generate_report_button()
 
     # Open a screening subject record
-    ReportsPage(page).click_nhs_number_link(page)
+    ReportsPage(page).click_fail_safe_reports_screening_subjects_with_inactive_open_episodes_link()
 
     # Verify the page title is "Subject Screening Summary"
     BasePage(page).bowel_cancer_screening_ntsh_page_title_contains_text(
         "Subject Screening Summary"
     )
 
-
 def test_failsafe_reports_subjects_ceased_due_to_date_of_birth_changes(
     page: Page,
 ) -> None:
@@ -170,14 +169,14 @@ def test_failsafe_reports_subjects_ceased_due_to_date_of_birth_changes(
     )
 
     # Open a screening subject record from the search results
-    ReportsPage(page).click_nhs_number_link(page)
+
+    ReportsPage(page).click_failsafe_reports_sub_links()
 
     # Verify page title is "Subject Demographic"
     BasePage(page).bowel_cancer_screening_page_title_contains_text(
         "Subject Demographic"
     )
 
-
 def test_failsafe_reports_allocate_sc_for_patient_movements_within_hub_boundaries(
     page: Page, general_properties: dict
 ) -> None:
@@ -211,7 +210,8 @@ def test_failsafe_reports_allocate_sc_for_patient_movements_within_hub_boundarie
     )
 
     # Open a screening subject record from the first row/first cell of the table
-    ReportsPage(page).click_nhs_number_link(page)
+    # nhs_number_link.click()
+    ReportsPage(page).click_failsafe_reports_sub_links()
 
     # Verify page title is "Set Patient's Screening Centre"
     BasePage(page).bowel_cancer_screening_page_title_contains_text(
@@ -309,8 +309,8 @@ def test_failsafe_reports_identify_and_link_new_gp(page: Page) -> None:
         report_timestamp
     )
 
-    # Open a screening subject record from the first row/second cell of the table
-    ReportsPage(page).click_nhs_number_link(page)
+    # Open a practice code from the first row/second cell of the table
+    ReportsPage(page).click_fail_safe_reports_identify_and_link_new_gp_practices_link()
 
     # Verify page title is "Link GP practice to Screening Centre"
     BasePage(page).bowel_cancer_screening_page_title_contains_text(
@@ -319,6 +319,7 @@ def test_failsafe_reports_identify_and_link_new_gp(page: Page) -> None:
 
 
 # Operational Reports
+
 def test_operational_reports_appointment_attendance_not_updated(
     page: Page, general_properties: dict
 ) -> None:
@@ -360,7 +361,7 @@ def test_operational_reports_appointment_attendance_not_updated(
     )
 
     # Open an appointment record from the report
-    ReportsPage(page).click_nhs_number_link(page)
+    ReportsPage(page).click_failsafe_reports_sub_links()
 
     # Verify the page title is "Appointment Detail"
     BasePage(page).bowel_cancer_screening_page_title_contains_text("Appointment Detail")

utils/table_util.py

@@ -0,0 +1,170 @@
+from playwright.sync_api import Page, Locator, expect
+from pages.base_page import BasePage
+import logging
+import secrets
+
+
+class TableUtils:
+    """
+    A utility class providing functionality around tables in BCSS.
+    """
+
+    def __init__(self, page: Page, table_locator: str) -> None:
+        """
+        Initializer for TableUtils.
+
+        Args:
+            page (playwright.sync_api.Page): The page the table is on.
+            table_locator (str): The locator value to use to find the table.
+
+        Returns:
+            A TableUtils object ready to use.
+        """
+        self.page = page
+        self.table_id = table_locator  # Store the table locator as a string
+        self.table = page.locator(
+            table_locator
+        )  # Create a locator object for the table
+
+    def get_column_index(self, column_name: str) -> int:
+        """
+        Finds the column index dynamically based on column name.
+        Works even if <thead> is missing and header is inside <tbody>.
+
+        :param column_name: Name of the column (e.g., 'NHS Number')
+        :return: 1-based column index or -1 if not found
+        """
+        header_row = (
+            self.table.locator("tbody tr").filter(has=self.page.locator("th")).first
+        )
+
+        headers = header_row.locator("th")
+        header_texts = headers.evaluate_all("ths => ths.map(th => th.innerText.trim())")
+
+        for index, header in enumerate(header_texts):
+            if column_name.lower() in header.lower():
+                return index + 1  # Convert to 1-based index
+        return -1  # Column not found
+
+    def click_first_link_in_column(self, column_name: str):
+        """
+        Clicks the first link found in the given column.
+        :param column_name: Name of the column containing links
+        """
+        column_index = self.get_column_index(column_name)
+        if column_index == -1:
+            raise ValueError(f"Column '{column_name}' not found in table")
+
+        # Create a dynamic locator for the esired column
+        link_locator = f"{self.table_id} tbody tr td:nth-child({column_index}) a"
+        links = self.page.locator(link_locator)
+
+        if links.count() > 0:
+            links.first.click()
+        else:
+            logging.info(f"No links found in column '{column_name}'")
+
+    def _format_inner_text(self, data: str) -> dict:
+        """
+        This formats the inner text of a row to make it easier to manage
+
+        Args:
+            data (str): The .inner_text() of a table row.
+
+        Returns:
+            A dict with each column item from the row identified with its position.
+        """
+        dict_to_return = {}
+        split_rows = data.split("\t")
+        pos = 1
+        for item in split_rows:
+            dict_to_return[pos] = item
+            pos += 1
+        return dict_to_return
+
+    def get_table_headers(self) -> dict:
+        """
+        This retrieves the headers from the table.
+
+        Returns:
+            A dict with each column item from the header row identified with its position.
+        """
+        headers = self.page.locator(f"{self.table_id} > thead tr").nth(0).inner_text()
+        return self._format_inner_text(headers)
+
+    def get_row_count(self) -> int:
+        """
+        This returns the total rows visible on the table (on the screen currently)
+
+        Returns:
+            An int with the total row count.
+        """
+        return self.page.locator(f"{self.table_id} > tbody tr").count()
+
+    def pick_row(self, row_number: int) -> Locator:
+        """
+        This picks a selected row from table
+
+        Args:
+            row_id (str): The row number of the row to select.
+
+        Returns:
+            A playwright.sync_api.Locator with the row object.
+        """
+        return self.page.locator(f"{self.table_id} > tbody tr").nth(row_number)
+
+    def pick_random_row(self) -> Locator:
+        """
+        This picks a random row from the visible rows in the table (full row)
+
+        Returns:
+            A playwright.sync_api.Locator with the row object.
+        """
+        return self.page.locator(f"{self.table_id} > tbody tr").nth(
+            secrets.randbelow(self.get_row_count())
+        )
+
+    def pick_random_row_number(self) -> int:
+        """
+        This picks a random row from the table in BCSS and returns its position
+
+        Returns:
+            An int representing a random row on the table.
+        """
+        return secrets.randbelow(self.get_row_count())
+
+    def get_row_data_with_headers(self, row_number: int) -> dict:
+        """
+        This picks a selected row from table
+
+        Args:
+            row_number (str): The row number of the row to select.
+
+        Returns:
+            A dict object with keys representing the headers, and values representing the row contents.
+        """
+        headers = self.get_table_headers()
+        row_data = self._format_inner_text(
+            self.page.locator(f"{self.table_id} > tbody tr")
+            .nth(row_number)
+            .inner_text()
+        )
+        results = {}
+
+        for key in headers:
+            results[headers[key]] = row_data[key]
+
+        return results
+
+    def get_full_table_with_headers(self) -> dict:
+        """
+        This returns the full table as a dict of rows, with each entry having a header key / value pair.
+        NOTE: The row count starts from 1 to represent the first row, not 0.
+
+        Returns:
+            A dict object with keys representing the rows, with values being a dict representing a header key / column value pair.
+        """
+        full_results = {}
+        for row in range(self.get_row_count()):
+            full_results[row + 1] = self.get_row_data_with_headers(row)
+        return full_results