Feature/bcss 20856 selenium to playwright datasets setup (#102)

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

<!-- Describe your changes in detail. -->
Adding two new scenarios from the selenium test framework.

## Context

<!-- Why is this change required? What problem does it solve? -->
Migration of tests from selenium to playwright

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

Author: adrianoaru-nhs

.gitignore

@@ -18,5 +18,6 @@ test-results/
 axe-reports/
 .env
 local.env
+.test_last_runs.json
 
 # Please, add your custom content below!

conftest.py

@@ -12,6 +12,8 @@
 from _pytest.python import Function
 from pytest_html.report_data import ReportData
 from utils.load_properties_file import PropertiesFile
+from _pytest.config.argparsing import Parser
+from _pytest.fixtures import FixtureRequest
 
 # Environment Variable Handling
 
@@ -64,3 +66,43 @@ def pytest_runtest_makereport(item: Function) -> typing.Generator[None, None, No
     if outcome is not None:
         report = outcome.get_result()
         report.description = str(item.function.__doc__)
+
+
+# Command-Line Options for Pytest
+
+
+def pytest_addoption(parser: Parser) -> None:
+    """
+    Add custom command-line options to pytest.
+
+    Args:
+        parser (Parser): The pytest parser object used to define CLI options.
+
+    Adds:
+        --subjects-to-run-for (int):
+            The number of subjects to run the test setup for.
+            Default is 10.
+
+    Example:
+        pytest tests/test_setup.py::test_setup_subjects_as_a259 --subjects-to-run-for=5
+    """
+    parser.addoption(
+        "--subjects-to-run-for",
+        action="store",
+        default="10",
+        help="Number of subjects to run the test setup for (default: 10)",
+    )
+
+
+@pytest.fixture
+def subjects_to_run_for(request: FixtureRequest) -> int:
+    """
+    Fixture to retrieve the value of the '--subjects-to-run-for' CLI argument.
+
+    Args:
+        request (FixtureRequest): Provides access to the requesting test context.
+
+    Returns:
+        int: The number of subjects specified via the CLI or default (10).
+    """
+    return int(request.config.getoption("--subjects-to-run-for"))  # type: ignore

docs/utility-guides/LastTestRun.md

@@ -0,0 +1,97 @@
+# Utility Guide: last_test_run
+
+The `last_test_run` utility provides a simple way to track when specific tests were last executed. It is designed to help you avoid running setups for tests multiple times and instead does a check to see if the test has been run today.
+
+---
+
+## Table of Contents
+
+- [Utility Guide: last\_test\_run](#utility-guide-last_test_run)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [When and Why to Use last\_test\_run](#when-and-why-to-use-last_test_run)
+  - [Required Arguments](#required-arguments)
+  - [last\_test\_run Methods](#last_test_run-methods)
+  - [Example Usage](#example-usage)
+  - [How It Works](#how-it-works)
+  - [Implementation Details](#implementation-details)
+
+---
+
+## Overview
+
+This utility manages a JSON file (`.test_last_runs.json`) that records the last date each test was run. It provides functions to load, save, and check this data, making it easy to implement "run once per day" logic in your test suite.
+
+---
+
+## When and Why to Use last_test_run
+
+You might want to use this utility in scenarios such as:
+
+- Avoiding repeated execution of slow or stateful tests within the same day.
+- Ensuring setup or tear down routines only run once per day.
+- Tracking test execution dates for reporting or debugging.
+
+---
+
+## Required Arguments
+
+Each function in this utility requires specific arguments:
+
+- `has_test_run_today(test_name: str) -> bool`:
+  - `test_name` (str): The unique name of the test to check.
+
+See the docstrings in the code for details on each function.
+
+---
+
+## last_test_run Methods
+
+**The main methods provided are:**
+
+- **load_last_run_data() -> Dict[str, Any]**
+  Loads the last run data from the JSON file. Returns a dictionary mapping test names to their last run date.
+
+- **save_last_run_data(data: Dict[str, Any]) -> None**
+  Saves the provided dictionary to the JSON file.
+
+- **has_test_run_today(test_name: str) -> `bool`**
+  Checks if the given test has already run today. If not, updates the record to mark it as run today.
+
+---
+
+## Example Usage
+
+```python
+from utils.last_test_run import has_test_run_today
+
+def test_expensive_setup():
+    if has_test_run_today("test_expensive_setup"):
+        print("Setup already run today, skipping.")
+        return
+    # ... perform expensive setup ...
+    print("Setup complete.")
+```
+
+---
+
+## How It Works
+
+- The utility stores a mapping of test names to their last run date in `.test_last_runs.json`.
+- When `has_test_run_today` is called, it checks if the test has already run today.
+  - If yes, it returns `True`.
+  - If no, it updates the file and returns `False`.
+
+---
+
+## Implementation Details
+
+- The JSON file is created in the project root if it does not exist.
+- If the file is empty or corrupted, the utility will safely return an empty dictionary and continue.
+- All functions are type-annotated and documented with docstrings for clarity.
+
+---
+
+> **Note:**
+> The `last_test_run` utility is available under `utils/last_test_run.py`.
+> See the source code for more details and to extend its functionality as needed.

pages/base_page.py

@@ -53,6 +53,7 @@ def __init__(self, page: Page):
             "#ntshPageTitle"
         )
         self.main_menu__header = self.page.locator("#ntshPageTitle")
+        self.log_in_page = self.page.get_by_role("button", name="Log in")
 
     def click_main_menu_link(self) -> None:
         """Click the Base Page 'Main Menu' link if it is visible."""
@@ -271,6 +272,10 @@ def handle_dialog(dialog: Dialog):
 
         self.page.once("dialog", handle_dialog)
 
+    def go_to_log_in_page(self) -> None:
+        """Click on the Log in button to navigate to the login page."""
+        self.click(self.log_in_page)
+
     def safe_accept_dialog_select_option(self, locator: Locator, option: str) -> None:
         """
         Safely accepts a dialog triggered by selecting a dropdown, avoiding the error: