Addressed commit warnings/errors

Andyg79 · Andyg79 · commit f9e9474fb39a · 2025-08-08T17:31:11.000+01:00
diff --git a/README.md b/README.md
@@ -6,86 +6,85 @@ This repository contains the automated UI test suite for the BCSS application, b
 
 Playwright is the recommended UI testing tool for NHS England, as outlined on the [NHS England Tech Radar](https://radar.engineering.england.nhs.uk/), and has been adopted here to modernize and streamline our testing workflows.
 
-
-# Origin of the Framework
+## Origin of the Framework
 
 This framework was originally based on the NHS England Playwright Python Blueprint and has since been tailored to meet the specific needs of the BCSS application. While the core utilities and conventions remain, the project has been extended with custom page object models (POMs) and new utility modules to support BCSS-specific workflows, data handling, and UI interactions.
 
 Note: This project is actively maintained and evolving.
 
-# Table of Contents
+## Table of Contents
 
 - [BCSS Playwright Test Suite](#bcss-playwright-test-suite)
-- [Origin of the Framework](#origin-of-the-framework)
-- [Table of Contents](#table-of-contents)
-- [Getting Started](#getting-started)
-  - [Prerequisites](#prerequisites)
-    - [1. Install Python 3.11 or higher](#1-install-python-311-or-higher)
-    - [2. Set up a virtual environment (recommended)](#2-set-up-a-virtual-environment-recommended)
-      - [First Create the virtual environment](#first-create-the-virtual-environment)
-      - [Next Activate the virtual environment](#next-activate-the-virtual-environment)
-    - [3. Install Playwright browser binaries](#3-install-playwright-browser-binaries)
-  - [Installation \& Configuration](#installation--configuration)
-    - [1. Install Dependencies](#1-install-dependencies)
-    - [2. Environment Variables](#2-environment-variables)
-    - [3. Test Configuration](#3-test-configuration)
-  - [Running Tests](#running-tests)
-    - [1. Basic Test Execution](#1-basic-test-execution)
-    - [2. Test Filtering](#2-test-filtering)
-    - [3. Viewing Trace Files](#3-viewing-trace-files)
-  - [Test Structure and Conventions](#test-structure-and-conventions)
-    - [1. File Organization](#1-file-organization)
-    - [2. Naming Conventions](#2-naming-conventions)
-    - [3. Test Function Anatomy](#3-test-function-anatomy)
-    - [4. Markers and Tags](#4-markers-and-tags)
-    - [5. Skipping and Expected Failures](#5-skipping-and-expected-failures)
-  - [Page Object Model (POM) Guidelines](#page-object-model-pom-guidelines)
-    - [1. What is a POM?](#1-what-is-a-pom)
-    - [2. Location and Structure](#2-location-and-structure)
-    - [3. Naming Convention](#3-naming-convention)
-    - [4. Anatomy of a Page Class](#4-anatomy-of-a-page-class)
-  - [Utility Modules](#utility-modules)
-    - [1. Purpose of Utility Modules](#1-purpose-of-utility-modules)
-    - [2. Example: Wait Utility](#2-example-wait-utility)
-    - [3. Best Practices](#3-best-practices)
-    - [4. Blueprint Utilities](#4-blueprint-utilities)
-  - [Contributing](#contributing)
-  - [Contacts](#contacts)
-  - [Licence](#licence)
-
-# Getting Started
-
-## Prerequisites
-
-Follow these steps to make sure your system is ready to run the BCSS test framework. 
-
-### 1. Install Python 3.11 or higher
+  - [Origin of the Framework](#origin-of-the-framework)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+      - [1. Install Python 3.11 or higher](#1-install-python-311-or-higher)
+      - [2. Set up a virtual environment (recommended)](#2-set-up-a-virtual-environment-recommended)
+        - [First Create the virtual environment](#first-create-the-virtual-environment)
+        - [Next Activate the virtual environment](#next-activate-the-virtual-environment)
+      - [3. Install Playwright browser binaries](#3-install-playwright-browser-binaries)
+    - [Installation \& Configuration](#installation--configuration)
+      - [1. Install Dependencies](#1-install-dependencies)
+      - [2. Environment Variables](#2-environment-variables)
+      - [3. Test Configuration](#3-test-configuration)
+    - [Running Tests](#running-tests)
+      - [1. Basic Test Execution](#1-basic-test-execution)
+      - [2. Test Filtering](#2-test-filtering)
+      - [3. Viewing Trace Files](#3-viewing-trace-files)
+    - [Test Structure and Conventions](#test-structure-and-conventions)
+      - [1. File Organization](#1-file-organization)
+      - [2. Naming Conventions](#2-naming-conventions)
+      - [3. Test Function Anatomy](#3-test-function-anatomy)
+      - [4. Markers and Tags](#4-markers-and-tags)
+      - [5. Skipping and Expected Failures](#5-skipping-and-expected-failures)
+    - [Page Object Model (POM) Guidelines](#page-object-model-pom-guidelines)
+      - [1. What is a POM?](#1-what-is-a-pom)
+      - [2. Location and Structure](#2-location-and-structure)
+      - [3. Naming Convention](#3-naming-convention)
+      - [4. Anatomy of a Page Class](#4-anatomy-of-a-page-class)
+    - [Utility Modules](#utility-modules)
+      - [1. Purpose of Utility Modules](#1-purpose-of-utility-modules)
+      - [2. Example: Wait Utility](#2-example-wait-utility)
+      - [3. Best Practices](#3-best-practices)
+      - [4. Blueprint Utilities](#4-blueprint-utilities)
+    - [Contributing](#contributing)
+    - [Contacts](#contacts)
+    - [Licence](#licence)
+
+## Getting Started
+
+### Prerequisites
+
+Follow these steps to make sure your system is ready to run the BCSS test framework.
+
+#### 1. Install Python 3.11 or higher
 
 This framework is built using Python, so you'll need to install it first. You can download the latest version from the official [Python](https://www.python.org/downloads/) website.
 
 To check if Python is already installed, open a terminal or command prompt and run:
 
 `python --version`
 
-### 2. Set up a virtual environment (recommended)
+#### 2. Set up a virtual environment (recommended)
 
 A virtual environment is like a sandbox—it keeps your project’s Python packages separate from everything else on your computer. This prevents version conflicts and makes your setup easier to manage.
 
 Note: If you are using an IDE such as Visual Studio Code or PyCharm, you will normally be prompted to do this automatically.
 
-#### First Create the virtual environment
+##### First Create the virtual environment
 
 To create and activate a virtual environment, open your terminal or command prompt in the root folder of the project (where requirements.txt lives), then run:
 
 `python -m venv .venv`
 
 This creates a folder called .venv that contains a clean Python environment just for this project.
 
-If you get an error like 'python not found', try using python3 instead:
+If you get an error like 'Python not found', try using Python3 instead:
 
 `python3 -m venv .venv`
 
-#### Next Activate the virtual environment
+##### Next Activate the virtual environment
 
 This step tells your terminal to use the Python version and packages inside .venv.
 
@@ -103,17 +102,17 @@ On macOS/Linux:
 
 Once activated, your terminal will show the virtual environment name (e.g. (.venv)), indicating you're working inside it.
 
-### 3. Install Playwright browser binaries
+#### 3. Install Playwright browser binaries
 
 Playwright uses real browsers to run tests. You’ll need to install these browser binaries once by running:
 
 `playwright install`
 
 This downloads the necessary versions of Chromium, Firefox, and WebKit so tests can run across different browser types.
 
-## Installation & Configuration
+### Installation & Configuration
 
-### 1. Install Dependencies
+#### 1. Install Dependencies
 
 Before configuring anything, make sure all required packages are installed by running:
 
@@ -126,21 +125,21 @@ This installs all Python dependencies listed in the `requirements.txt` file, inc
 
 Note: If you're using a virtual environment (recommended), activate it before running the install command (see previous steps).
 
-### 2. Environment Variables
+#### 2. Environment Variables
 
 Create a `.env` file in the project root to store sensitive configuration values like credentials, URLs, or feature flags. Example:
 
-```
+```Bash
 BASE_URL=https://bcss.example.com
 USERNAME=test_user
 PASSWORD=secure_password123
 ```
 
-These variables are loaded automatically by the framework using python-dotenv, keeping secrets out of the codebase.
+These variables are loaded automatically by the framework using `python-dotenv`, keeping secrets out of the codebase.
 The actual values required for the `.env` file can be obtained from one of the testers already using this framework.
-Important Note: Ensure that `.env` is added to your `.gitignore` to avoid accidentally committing secrets. 
+Important Note: Ensure that `.env` is added to your `.gitignore` to avoid accidentally committing secrets.
 
-### 3. Test Configuration
+#### 3. Test Configuration
 
 You can test the configuration has worked by running our example tests, which can be done using the following command (this will run all tests with tracing reports turned on, and in headed mode so you can see the browser execution):
 
@@ -149,9 +148,9 @@ You can test the configuration has worked by running our example tests, which ca
 Alternatively if you are using Visual Studio Code as your IDE, we have pre-configured this project to work with the
 [Testing functionality](https://code.visualstudio.com/docs/editor/testing) so the example tests should be discovered automatically.
 
-## Running Tests
+### Running Tests
 
-### 1. Basic Test Execution
+#### 1. Basic Test Execution
 
 To run all tests with tracing enabled:
 
@@ -163,7 +162,7 @@ To run a specific test file:
 
 Tracing captures detailed information about each test run, including browser actions, network requests, and DOM snapshots.
 
-### 2. Test Filtering
+#### 2. Test Filtering
 
 Use markers or keywords to run subsets of tests:
 
@@ -174,7 +173,7 @@ You can combine flags like `-v (verbose)` and `--maxfail=1` to control output an
 
 `pytest -v --maxfail=1 --tracing on`
 
-### 3. Viewing Trace Files
+#### 3. Viewing Trace Files
 
 After running tests with tracing enabled, trace files are saved in the test-results folder.
 
@@ -188,9 +187,9 @@ Use the interactive viewer to explore browser actions, network activity, and DOM
 
 This is especially useful for debugging failed tests or understanding complex UI flows.
 
-## Test Structure and Conventions
+### Test Structure and Conventions
 
-### 1. File Organization
+#### 1. File Organization
 
 All tests are located in the tests/ directory.
 
@@ -200,7 +199,7 @@ Each feature or module has its own test file, e.g.:
 
 `test_user_profile.py`
 
-### 2. Naming Conventions
+#### 2. Naming Conventions
 
 Test files: test_<feature>.py
 Example: test_login_to_bcss.py
@@ -209,11 +208,11 @@ Page Object Models: <page>_page.py
 Example: login_failure_screen_page.py
 
 
-### 3. Test Function Anatomy
+#### 3. Test Function Anatomy
 
 Each test typically follows this structure:
 
-```python
+```Python
 def test_user_can_login(page):
     login_page = LoginPage(page)
     login_page.navigate()
@@ -222,16 +221,14 @@ def test_user_can_login(page):
 ```
 
 - Use Page Object Model (POM) for UI interactions
-
 - Keep assertions clear and focused
+- Avoid hard coded waits - prefer expect() or Playwright’s built-in waiting mechanisms
 
-- Avoid hardcoded waits - prefer expect() or Playwright’s built-in waiting mechanisms
-
-### 4. Markers and Tags
+#### 4. Markers and Tags
 
 Use @pytest.mark.<tag> to run a subset or tests as required:
 
-```python
+```Python
 @pytest.mark.smoke
 def test_basic_login(page):
 ```
@@ -245,11 +242,11 @@ smoke: quick validation of core functionality
 regression: full suite for release validation
 slow: long-running tests
 
-### 5. Skipping and Expected Failures
+#### 5. Skipping and Expected Failures
 
 Use Pytest decorators to manage test behavior:
 
-```python
+```Python
 @pytest.mark.skip(reason="Feature not implemented yet")
 def test_future_feature(page):
 
@@ -258,22 +255,23 @@ def test_future_feature(page):
 def test_login_with_invalid_credentials(page):
 ```
 
-## Page Object Model (POM) Guidelines
+### Page Object Model (POM) Guidelines
+
+#### 1. What is a POM?
 
-### 1. What is a POM?
 A Page Object Model is a design pattern that encapsulates UI interactions for a specific page or component into a dedicated class. This keeps test code clean, readable, and reusable.
 
 Instead of writing raw selectors and actions in your test, you use methods from a page class:
 
-```python
+```Python
 def test_user_can_login(page):
     login_page = LoginPage(page)
     login_page.navigate()
     login_page.login("user@example.com", "securepassword")
     assert login_page.is_logged_in()
 ```
 
-### 2. Location and Structure
+#### 2. Location and Structure
 
 All POMs are stored in the pages/ directory.
 
@@ -283,14 +281,14 @@ Each file represents a single page or component, for example:
 - dashboard_page.py
 - user_profile_page.py
 
-### 3. Naming Convention
+#### 3. Naming Convention
 
 - Class names: LoginPage, DashboardPage, etc.
 - File names: lowercase with underscores, matching the class name (e.g. login_page.py)
 
-### 4. Anatomy of a Page Class
+#### 4. Anatomy of a Page Class
 
-```python
+```Python
 class LoginPage:
     def __init__(self, page):
         self.page = page
@@ -310,19 +308,19 @@ class LoginPage:
         return self.page.locator("text=Welcome").is_visible()
 ```
 
-## Utility Modules
+### Utility Modules
 
 Utility modules help you abstract common functionality that doesn’t belong in a specific page class. This keeps your POMs lean and your tests DRY (Don’t Repeat Yourself).
 
-### 1. Purpose of Utility Modules
+#### 1. Purpose of Utility Modules
 
 - Handle reusable actions (e.g. login, file uploads, date pickers)
 - Provide custom assertions or wait conditions
 - Manage test data generation or environment setup
 
-### 2. Example: Wait Utility
+#### 2. Example: Wait Utility
 
-```python
+```Python
 # utils/wait_utils.py
 
 from playwright.sync_api import expect
@@ -331,14 +329,14 @@ def wait_for_element(page, selector, timeout=5000):
     expect(page.locator(selector)).to_be_visible(timeout=timeout)
 ```
 
-### 3. Best Practices
+#### 3. Best Practices
 
 - Keep utilities modular and single-purpose.
-- Avoid hardcoding values—use config files or environment variables.
+- Avoid hard coding values - use configuration files or environment variables.
 - Document each function with a short docstring.
 - Use type hints for clarity and IDE support.
 
-### 4. Blueprint Utilities
+#### 4. Blueprint Utilities
 
 This blueprint provides the following utility classes, that can be used to aid in testing:
 
@@ -349,17 +347,17 @@ This blueprint provides the following utility classes, that can be used to aid i
 | [NHSNumberTools](./docs/utility-guides/NHSNumberTools.md)     | Basic tools for working with NHS numbers.    |
 | [User Tools](./docs/utility-guides/UserTools.md)              | Basic user management tool.                  |
 
-## Contributing
+### Contributing
 
 Further guidance on contributing to this project can be found in our [contribution](./CONTRIBUTING.md) page.
 
-## Contacts
+### Contacts
 
 If you have any ideas or require support for this project, please [raise an issue via this repository](https://github.com/nhs-england-tools/playwright-python-blueprint/issues/new/choose) using the appropriate template.
 
 If you have any general queries regarding this blueprint, please contact [dave.harding1@nhs.net](mailto:dave.harding1@nhs.net).
 
-## Licence
+### Licence
 
 Unless stated otherwise, the codebase is released under the [MIT License](LICENCE.md). This covers both the codebase and any sample code in the documentation.
 
