Feature/bcss 21031 selenium to playwright manually cease a subject (#114)

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

<!-- Describe your changes in detail. -->
Added tests and any required utils / updates for the feature: manually
cease a subject.
This includes all of the test scenarios from the feature file and the
addition of the manual_cease util and util guide.

## Context

<!-- Why is this change required? What problem does it solve? -->
This is part of the Selenium to Playwright migration work

## Type of changes

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

---------

Signed-off-by: AndyG <[email protected]>
Co-authored-by: adrianoaru-nhs <[email protected]>

Author: Andyg79

docs/utility-guides/ManualCease.md

@@ -0,0 +1,115 @@
+# Utility Guide: Manual Cease Workflow
+
+This utility facilitates creation, UI automation, and database verification for manual cease workflows in the BCSS Playwright test suite.<br> It includes:
+
+  1. Generating a subject eligible for manual cease via database creation and timeline event execution.
+  2. Performing the cease workflow through the browser UI, supporting both 'immediate' and 'with disclaimer' flows.
+  3. Validating dynamic database fields after cease is completed.
+
+## Table of Contents
+
+- [Utility Guide: Manual Cease Workflow](#utility-guide-manual-cease-workflow)
+  - [Table of Contents](#table-of-contents)
+  - [Creating Subjects for Cease](#creating-subjects-for-cease)
+    - [Arguments](#arguments)
+    - [How to use this method](#how-to-use-this-method)
+  - [UI Workflow Methods](#ui-workflow-methods)
+    - [Standard Flow (with Disclaimer)](#standard-flow-with-disclaimer)
+    - [Immediate Flow](#immediate-flow)
+  - [DB Verification](#db-verification)
+    - [Arguments](#arguments-1)
+    - [How to use this method](#how-to-use-this-method-1)
+  - [Enums and Constants](#enums-and-constants)
+    - [EXPECT markers](#expect-markers)
+    - [Status \& Reason Enums](#status--reason-enums)
+
+## Creating Subjects for Cease
+
+The `create_manual_cease_ready_subject` method creates a subject with Inactive screening status and executes timed events, preparing it for the cease flow.
+
+### Arguments
+
+  `screening_centre`:
+    Type: str
+    Screening centre to associate with the subject. Defaults to "BCS002".
+
+  `base_age`:
+    Type: int
+    Age threshold used during subject creation. Defaults to 75.
+
+### How to use this method
+
+```python
+from utils.manual_cease_util import create_manual_cease_ready_subject
+nhs_number = create_manual_cease_ready_subject(screening_centre="BCS002", base_age=75)
+```
+
+## UI Workflow Methods
+
+### Standard Flow (with Disclaimer)
+
+`process_manual_cease_with_disclaimer(page: Page, reason: str = "Informed Dissent")` automates the full cease workflow including disclaimer steps.
+
+```python
+from utils.manual_cease_util import process_manual_cease_with_disclaimer
+process_manual_cease_with_disclaimer(page, reason="Moved Away")
+```
+
+### Immediate Flow
+
+`process_manual_cease_immediate(page: Page, reason: str = "Informed Dissent")` performs the cease workflow without recording disclaimer letters.
+
+```python
+from utils.manual_cease_util import process_manual_cease_immediate
+process_manual_cease_immediate(page, reason="Deceased")
+```
+
+## DB Verification
+
+The method `verify_manual_cease_db_fields_dynamic(nhs_number: str, expected: dict[str, object])` dynamically validates updated DB fields based on supplied expectations.
+
+### Arguments
+
+  nhs_number:
+    Type: str
+    NHS number of the subject to validate.
+
+  expected:
+    Type: dict[str, object]
+    A dictionary mapping human-readable field labels to expected values. Supports assertions like TODAY, NULL, UNCHANGED, or direct values.
+
+### How to use this method
+
+```python
+from utils.manual_cease_util import verify_manual_cease_db_fields_dynamic, EXPECT
+
+verify_manual_cease_db_fields_dynamic(nhs_number, {
+    "Screening Status": 4008,
+    "Screening Status Reason": 43,
+    "Ceased Confirmation Date": EXPECT.TODAY,
+    "Ceased Confirmation Details": "AUTO TEST: notes"
+})
+```
+
+## Enums and Constants
+
+### EXPECT markers
+
+Used in DB assertions to express flexible expectations.
+  EXPECT.TODAY: Field must match today's date.
+  EXPECT.NULL: Field must be null.
+  EXPECT.UNCHANGED: Field must exist but is not asserted.
+  EXPECT.MATCH_USER_ID: Field must be a valid user ID.
+
+### Status & Reason Enums
+
+The utility includes enums for easier mapping in test code:
+
+```python
+from utils.manual_cease_util import ScreeningStatus, ScreeningStatusReason
+
+ScreeningStatus.CEASED        # → 4008
+ScreeningStatusReason.DECEASED  # → 45
+```
+
+Refer to the source code in `utils/manual_cease_util.py` for additional mappings and helper logic.

pages/manual_cease/manual_cease_page.py

@@ -0,0 +1,95 @@
+from playwright.sync_api import Page
+import logging
+from datetime import datetime
+from pages.base_page import BasePage
+
+
+class ManualCeasePage(BasePage):
+    """This class contains locators to interact with the manual cease page."""
+
+    def __init__(self, page: Page):
+        self.page = page
+        self.request_cease_button = page.locator("input[name='BTN_REQUEST_CEASE']")
+        self.cease_reason_dropdown = page.locator("#A_C_RequestCeaseReason")
+        self.notes_textbox = page.get_by_role("textbox", name="Notes (up to 500 char)")
+        self.date_confirmed_field = page.get_by_label("Date Confirmed")
+        self.confirm_cease_button = page.get_by_role("button", name="Confirm Cease")
+        self.save_request_cease_button = page.locator(
+            "input[name='BTN_SAVE'][value='Save Request Cease']"
+        )
+        self.summary_table = page.locator("#screeningSummaryTable")
+        self.record_disclaimer_sent_button = page.get_by_role(
+            "button", name="Record Disclaimer Letter Sent"
+        )
+        self.confirm_disclaimer_sent_button = page.get_by_role("button", name="Confirm")
+        self.record_return_disclaimer_button = page.get_by_role(
+            "button", name="Record Return of Disclaimer Letter"
+        )
+        self.notes_field = page.get_by_label("Notes")
+
+    def click_request_cease(self) -> None:
+        """Clicks the 'Request Cease' button."""
+        self.click(self.request_cease_button)
+
+    def select_cease_reason(self, reason: str) -> None:
+        """Selects a given cease reason from the dropdown.
+        Args:
+            reason (str): The reason to select from the dropdown.
+        """
+        self.cease_reason_dropdown.select_option(label=reason)
+
+    def click_save_request_cease(self) -> None:
+        """Clicks the 'Save Request Cease' button."""
+        self.click(self.save_request_cease_button)
+
+    def record_disclaimer_sent(self) -> None:
+        """Clicks the 'Record the disclaimer letter has been sent' button."""
+        self.click(self.record_disclaimer_sent_button)
+
+    def confirm_disclaimer_sent(self) -> None:
+        """Clicks the 'Confirm disclaimer letter has been sent' button."""
+        self.click(self.confirm_disclaimer_sent_button)
+
+    def record_return_of_disclaimer(self) -> None:
+        """Clicks the 'Record the return of the disclaimer letter' button."""
+        self.click(self.record_return_disclaimer_button)
+
+    def fill_notes_and_date(self, notes: str = "AUTO TEST: notes") -> None:
+        """Fills in notes and today's date in the form.
+        Args:
+            notes (str): Notes to fill in the text box.
+        """
+        self.notes_field.fill(notes)
+        today_str = datetime.today().strftime("%d/%m/%Y")
+        self.date_confirmed_field.fill(today_str)
+
+    def confirm_cease(self) -> None:
+        """Clicks the 'Confirm cease' button and accepts dialog."""
+        self.safe_accept_dialog(self.confirm_cease_button)
+
+    def fill_notes_if_visible(self, notes: str = "AUTO TEST: notes") -> None:
+        """Fills in notes if the notes textbox is visible.
+        Args:
+            notes (str): Notes to fill in the text box.
+        """
+        if self.notes_textbox.is_visible():
+            self.notes_textbox.fill(notes)
+
+    def fill_date_if_visible(self, date_str: str) -> None:
+        """Fills in today's date if the date confirmed field is visible.
+        Args:
+            date_str (str): Date to fill in the date confirmed field.
+        """
+        if self.date_confirmed_field.is_visible():
+            self.date_confirmed_field.fill(date_str)
+
+    def confirm_or_save_cease(self) -> None:
+        """Confirms the cease action via either 'Confirm Cease' or 'Save Request Cease' button."""
+        if self.confirm_cease_button.is_visible():
+            BasePage(self.page).safe_accept_dialog(self.confirm_cease_button)
+
+        elif self.save_request_cease_button.is_visible():
+            self.click(self.save_request_cease_button)
+        else:
+            logging.error("No cease confirmation button found!")
+            raise RuntimeError("Cease button not found on the page")

pytest.ini

@@ -45,6 +45,7 @@ markers =
     subject_search: tests that are part of the subject search test suite
     investigation_dataset_tests: tests that are part of the investigation dataset test suite
     skip_before_test: tests that will not use the before_test fixture
+    manual_cease_tests: tests that are part of the manual cease test suite
     bcss_additional_tests: tests that are part of the BCSS additional tests test suite
     colonoscopy_dataset_tests: tests that are part of the colonoscopy datasets test suite
     fobt_diagnosis_date_entry_tests: tests that are part of fobt subject episodes record diagnosis date