Feature/bcss 20605 regression tests subject notes (#100)

<!-- markdownlint-disable-next-line first-line-heading -->
Converting the subject notes tests from the selenium framework to
playwright python

<!-- Describe your changes in detail. -->
Converting the subject notes test from selenium to playwright

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

This activity is part of tests migration to playwright to make sure
tests are running without any issues.

<!-- 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: mepr1

docs/utility-guides/SubjectNotes.md

@@ -0,0 +1,28 @@
+# Utility Guide: Note Test Utilities
+
+The **Note Test Utility** module provides reusable helper functions for verifying and comparing note data during test automation of screening subjects in BCSS.
+It includes helpers for:
+
+1. Fetching supporting notes from the database.
+2. Verifying that a note matches expected values from the DB or UI.
+3. Confirming that a removed note is archived properly as obsolete.
+
+## Table of Contents
+
+- [Utility Guide: Note Test Utilities](#utility-guide-note-test-utilities)
+  - [Table of Contents](#table-of-contents)
+  - [Using These Utilities](#using-these-utilities)
+
+---
+
+## Using These Utilities
+
+You can import functions into your test files like so:
+
+```python
+from utils.note_test_util import (
+    fetch_supporting_notes_from_db,
+    verify_note_content_matches_expected,
+    verify_note_content_ui_vs_db,
+    verify_note_removal_and_obsolete_transition,
+)

pages/base_page.py

@@ -270,3 +270,18 @@ def handle_dialog(dialog: Dialog):
             dialog.dismiss()  # Dismiss dialog
 
         self.page.once("dialog", handle_dialog)
+
+    def safe_accept_dialog_select_option(self, locator: Locator, option: str) -> None:
+        """
+        Safely accepts a dialog triggered by selecting a dropdown, avoiding the error:
+        playwright._impl._errors.Error: Dialog.accept: Cannot accept dialog which is already handled!
+        If no dialog appears, continues without error.
+        Args:
+            locator (Locator): The locator that triggers the dialog when clicked.
+            example: If clicking a save button opens a dialog, pass that save button's locator.
+        """
+        self.page.once("dialog", self._accept_dialog)
+        try:
+            locator.select_option(option)
+        except Exception as e:
+            logging.error(f"Option selection failed: {e}")

pages/screening_subject_search/subject_events_notes.py

@@ -0,0 +1,147 @@
+from playwright.sync_api import Page, Locator
+from pages.base_page import BasePage
+from enum import StrEnum
+import logging
+import pytest
+from utils.table_util import TableUtils
+
+
+class SubjectEventsNotes(BasePage):
+    """Subject Events Notes Page locators, and methods for interacting with the page."""
+
+    def __init__(self, page: Page):
+        super().__init__(page)
+        self.page = page
+        self.table_utils = TableUtils(
+            page, "#displayRS"
+        )  # Initialize TableUtils for the table with id="displayRS"
+        # Subject Events Notes - page filters
+        self.additional_care_note_checkbox = self.page.get_by_label(
+            "Additional Care Needs Note"
+        )
+        self.subject_note_checkbox = self.page.get_by_label("Subject Note")
+        self.kit_note_checkbox = self.page.get_by_label("Kit Note")
+        self.note_title = self.page.get_by_label("Note Title")
+        self.additional_care_note_type = self.page.locator("#UI_ADDITIONAL_CARE_NEED")
+        self.notes_upto_500_char = self.page.get_by_label("Notes (up to 500 char)")
+        self.update_notes_button = self.page.get_by_role("button", name="Update Notes")
+        self.note_type = self.page.locator("#UI_ADDITIONAL_CARE_NEED_FILTER")
+        self.note_status = self.page.locator(
+            "//table[@id='displayRS']/tbody/tr[2]/td[3]/select"
+        )
+        self.episode_note_status = self.page.locator(
+            "//table[@id='displayRS']/tbody/tr[2]/td[4]/select"
+        )
+
+    def select_additional_care_note(self) -> None:
+        """Selects the 'Additional Care Needs Note' checkbox."""
+        self.additional_care_note_checkbox.check()
+
+    def select_subject_note(self) -> None:
+        """Selects the 'subject note' checkbox."""
+        self.subject_note_checkbox.check()
+
+    def select_kit_note(self) -> None:
+        """Selects the 'kit note' checkbox."""
+        self.kit_note_checkbox.check()
+
+    def select_additional_care_note_type(self, option: str) -> None:
+        """Selects an option from the 'Additional Care Note Type' dropdown.
+
+        Args:
+            option (AdditionalCareNoteTypeOptions): The option to select from the dropdown.
+                                                Use one of the predefined values from the
+                                                AdditionalCareNoteTypeOptions enum, such as:
+                                                - AdditionalCareNoteTypeOptions.LEARNING_DISABILITY
+                                                - AdditionalCareNoteTypeOptions.SIGHT_DISABILITY
+                                                - AdditionalCareNoteTypeOptions.HEARING_DISABILITY
+                                                - AdditionalCareNoteTypeOptions.MOBILITY_DISABILITY
+                                                - AdditionalCareNoteTypeOptions.MANUAL_DEXTERITY
+                                                - AdditionalCareNoteTypeOptions.SPEECH_DISABILITY
+                                                - AdditionalCareNoteTypeOptions.CONTINENCE_DISABILITY
+                                                - AdditionalCareNoteTypeOptions.LANGUAGE
+                                                - AdditionalCareNoteTypeOptions.OTHER
+        """
+        self.additional_care_note_type.select_option(option)
+
+    def select_note_type(self, option: str) -> None:
+        """
+        Selects a note type from the dropdown menu.
+
+        Args:
+            option (str): The value of the option to select from the dropdown.
+        """
+        self.note_type.select_option(option)
+
+    def select_note_status(self, option: str) -> None:
+        """
+        Selects a note status from the dropdown menu.
+
+        Args:
+            option (str): The value of the option to select from the dropdown.
+        """
+        self.note_status.select_option(option)
+
+    def fill_note_title(self, title: str) -> None:
+        """Fills the title field with the provided text."""
+        self.note_title.fill(title)
+
+    def fill_notes(self, notes: str) -> None:
+        """Fills the notes field with the provided text."""
+        self.notes_upto_500_char.fill(notes)
+
+    def accept_dialog_and_update_notes(self) -> None:
+        """Clicks the 'Update Notes' button and handles the dialog by clicking 'OK'."""
+        self.page.once("dialog", lambda dialog: dialog.accept())
+        self.update_notes_button.click()
+
+    def accept_dialog_and_add_replacement_note(self) -> None:
+        """
+        Dismisses the dialog and clicks the 'Add Replacement Note' button.
+        """
+        self.page.once("dialog", lambda dialog: dialog.accept())
+        self.page.get_by_role("button", name="Add Replacement Note").click()
+
+    def get_title_and_note_from_row(self, row_number: int = 0) -> dict:
+        """
+        Extracts title and note from a specific row's 'Notes' column using dynamic column index.
+        """
+        cell_text = self.table_utils.get_cell_value("Notes", row_number)
+        lines = cell_text.split("\n\n")
+        title = lines[0].strip() if len(lines) > 0 else ""
+        note = lines[1].strip() if len(lines) > 1 else ""
+        logging.info(
+            f"Extracted title: '{title}' and note: '{note}' from row {row_number}"
+        )
+        return {"title": title, "note": note}
+
+
+class AdditionalCareNoteTypeOptions(StrEnum):
+    """Enum for AdditionalCareNoteTypeOptions."""
+
+    LEARNING_DISABILITY = "4120"
+    SIGHT_DISABILITY = "4121"
+    HEARING_DISABILITY = "4122"
+    MOBILITY_DISABILITY = "4123"
+    MANUAL_DEXTERITY = "4124"
+    SPEECH_DISABILITY = "4125"
+    CONTINENCE_DISABILITY = "4126"
+    LANGUAGE = "4128"
+    OTHER = "4127"
+
+
+class NotesOptions(StrEnum):
+    """Enum for NoteTypeOptions."""
+
+    SUBJECT_NOTE = "4111"
+    KIT_NOTE = "308015"
+    ADDITIONAL_CARE_NOTE = "4112"
+    EPISODE_NOTE = "4110"
+
+
+class NotesStatusOptions(StrEnum):
+    """Enum for NoteStatusOptions."""
+
+    ACTIVE = "4100"
+    OBSOLETE = "4101"
+    INVALID = "4102"

pages/screening_subject_search/subject_screening_search_page.py

@@ -17,6 +17,7 @@ def __init__(self, page: Page):
         self.demographics_filter = self.page.get_by_role("radio", name="Demographics")
         self.datasets_filter = self.page.get_by_role("radio", name="Datasets")
         self.nhs_number_filter = self.page.get_by_role("textbox", name="NHS Number")
+        self.nhs_number_input = self.page.get_by_label("NHS Number")
         self.surname_filter = self.page.locator("#A_C_Surname")
         self.soundex_filter = self.page.get_by_role("checkbox", name="Use soundex")
         self.forename_filter = self.page.get_by_role("textbox", name="Forename")

pages/screening_subject_search/subject_screening_summary_page.py

@@ -54,6 +54,7 @@ def __init__(self, page: Page):
         self.advance_fobt_screening_episode_button = self.page.get_by_role(
             "button", name="Advance FOBT Screening Episode"
         )
+        self.additional_care_note_link = self.page.get_by_role("link", name="(AN)")
         self.temporary_address_icon = self.page.get_by_role(
             "link", name="The person has a current"
         )
@@ -195,6 +196,47 @@ def click_advance_fobt_screening_episode_button(self) -> None:
         except Exception as e:
             pytest.fail(f"Unable to advance the episode: {e}")
 
+    def verify_additional_care_note_visible(self) -> None:
+        """Verifies that the '(AN)' link is visible."""
+        expect(self.additional_care_note_link).to_be_visible()
+
+    def verify_note_link_present(self, note_type_name: str) -> None:
+        """
+        Verifies that the link for the specified note type is visible on the page.
+
+        Args:
+            note_type_name (str): The name of the note type to check (e.g., 'Additional Care Note', 'Episode Note').
+
+        Raises:
+            AssertionError: If the link is not visible on the page.
+        """
+        logging.info(f"Checking if the '{note_type_name}' link is visible.")
+        note_link_locator = self.page.get_by_role(
+            "link", name=f"({note_type_name})"
+        )  # Dynamic locator for the note type link
+        assert (
+            note_link_locator.is_visible()
+        ), f"'{note_type_name}' link is not visible, but it should be."
+        logging.info(f"Verified: '{note_type_name}' link is visible.")
+
+    def verify_note_link_not_present(self, note_type_name: str) -> None:
+        """
+        Verifies that the link for the specified note type is not visible on the page.
+
+        Args:
+            note_type_name (str): The name of the note type to check (e.g., 'Additional Care Note', 'Episode Note').
+
+        Raises:
+            AssertionError: If the link is visible on the page.
+        """
+        logging.info(f"Checking if the '{note_type_name}' link is not visible.")
+        note_link_locator = self.page.get_by_role(
+            "link", name=f"({note_type_name})"
+        )  # Dynamic locator for the note type link
+        assert (
+            not note_link_locator.is_visible()
+        ), f"'{note_type_name}' link is visible, but it should not be."
+        logging.info(f"Verified: '{note_type_name}' link is not visible.")
     def verify_temporary_address_popup_visible(self) -> None:
         """Verify that the temporary address popup is visible."""
         try:

pytest.ini

@@ -39,5 +39,6 @@ markers =
     vpn_required: for tests that require a VPN connection
     regression: tests that are part of the regression test suite
     call_and_recall: tests that are part of the call and recall test suite
+    note_tests: tests that are part of the notes test suite
     subject_tests: tests that are part of the subject tests suite
     subject_search: tests that are part of the subject search test suite

tests/bcss_tests.properties

@@ -28,3 +28,17 @@ episode_closed_date=22/09/2020
 daily_invitation_rate=28
 fobt_daily_invitation_rate=6
 weekly_invitation_rate=130
+
+# ----------------------------------
+# Subject Notes Test DATA
+# ----------------------------------
+additional_care_note_name=AN
+additional_care_note_type_value=4112
+episode_note_name=EN
+episode_note_type_value=4110
+subject_note_name=SN
+subject_note_type_value=4111
+kit_note_name=KN
+kit_note_type_value=308015
+note_status_active=4100
+note_status_obsolete=4101