Playwright Python Blueprint

This project is designed to provide a blueprint to allow for development teams to start quickly developing UI tests using Playwright Python, providing the base framework and utilities to allow for initial focus on writing tests, rather than configuration of the framework itself. Playwright is the current mainstream UI testing tool for NHS England, as outlined on the NHS England Tech Radar.

NOTE: This project is currently under initial development so isn't finalised, but should work if you want to experiment with Playwright Python.

Table of Contents

• Playwright Python Blueprint
  • Table of Contents
  • Setup
    • Prerequisites
    • Configuration
  • Getting Started
  • Utilities
  • Using Environment Variables For Secrets
  • Contributing
  • Contacts
  • Licence

Setup

You can clone this whole repository using the code below:

git clone https://github.com/nhs-england-tools/playwright-python-blueprint.git

Prerequisites

To utilise the blueprint code, you will need to have the following installed:

• Python 3.12 or greater

Whilst not required to get started, you may also want to configure a Python virtual environment for your project before proceeding with the configuration. If you are using an IDE such as Visual Studio Code or PyCharm, you will normally be prompted to do this automatically.

Configuration

To get started using Playwright and with the examples provided, use the following commands:

pip install -r requirements.txt
playwright install --with-deps

This will install all the necessary packages for executing Playwright tests, and install Playwright ready for use by the framework. 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):

pytest --tracing on --headed

Alternatively if you are using Visual Studio Code as your IDE, we have pre-configured this project to work with the Testing functionality so the example tests should be discovered automatically.

Getting Started

NOTE: This section is currently under development and requires further work, so links to pages within this repository may not be very useful at this stage.

Once you've confirmed your installation is working, please take a look at the following guides on getting started with Playwright Python.

1. Understanding Playwright Python
2. Blueprint File Breakdown

We've also created a Quick Reference Guide for common commands and actions you may regularly perform using this blueprint.

For additional reading and guidance on writing tests, we also recommend reviewing the Playwright Python documentation.

Utilities

This blueprint provides the following utility classes, that can be used to aid in testing:

Utility	Description
Axe	Accessibility scanning using axe-core.
Date Time Utility	Basic functionality for managing date/times.
NHSNumberTools	Basic tools for working with NHS numbers.
User Tools	Basic user management tool.

Using Environment Variables For Secrets

This blueprint provides functionality for saving secret / sensitive values that you would not want present in the codebase, but require to execute tests locally (such as passwords or API keys). A local.env file can be generated by running the following script:

python ./setup_env_file.py

This script file is design to be amended / updated as your project evolves, so as more sensitive values are required for executing tests, the list of keys provided can be updated so for subsequent runs of the script, all the expected keys are populated within the local.env file (which will need their values setting manually). The intent is that this script can be run to onboard new team members and provide a local file with all the variables they need to populate.

The local.env file (if present), is read at the start of any test session (via the conftest.py file) and any variables can be accessed by using the Python os library like so:

# Import the OS library
import os

# Access environment variable
os.getenv('<key_from_local.env>')

The local.env file is set in the .gitignore file, so by default it will not commit if amended.

NOTE: You should never commit this file or any secrets in the codebase directly.

Contributing

Further guidance on contributing to this project can be found in our contribution page.

Contacts

If you have any ideas or require support for this project, please raise an issue via this repository using the appropriate template.

If you have any general queries regarding this blueprint, please contact dave.harding1@nhs.net.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

Any HTML or Markdown documentation is © Crown Copyright and available under the terms of the Open Government Licence v3.0.