Merge pull request #811 from NHSDigital/update-readme

Update README

Author: jf-x-dev

.env.generic

@@ -7,15 +7,16 @@ BASIC_AUTH_USERNAME=
 BASIC_AUTH_PASSWORD=
 BASIC_AUTH_TOKEN=
 
-# set true to set the feature flags in the flipper page
+# all of the IMMS_* values need to be set to run imms api tests
+IMMS_BASE_URL=https://int.api.service.nhs.uk/
+IMMS_API_PEM=
+IMMS_API_KEY=
+IMMS_API_KID=
+
+# set true to set feature flags in the flipper page
 # basic_auth, api and dev_tools will be set by default
+# additional feature flags can be provided as a comma separated list
 SET_FEATURE_FLAGS=false
 ADDITIONAL_FEATURE_FLAGS=
 
 SCREENSHOT_ALL_STEPS=false
-
-IMMS_API_PEM=
-IMMS_API_KEY=
-IMMS_API_KID=
-
-IMMS_BASE_URL=https://int.api.service.nhs.uk/

README.md

@@ -57,7 +57,7 @@ There are two ways to run commands with `uv`
     $ pytest
     ```
 
-### CLI arguments
+### Playwright CLI arguments
 
 Playwright offers many [CLI arguments] which can be used when running tests. Some useful ones are highlighted here:
 
@@ -81,35 +81,38 @@ run the tests in headed mode, use the following command:
 ```shell
 $ pytest --headed
 ```
+#### Tracing
 
-#### Slow motion
-
-When running the tests locally in headed mode, it can be useful to make the
-steps artificially slower to see what's happening at each point. To introduce
-a 1-second delay, use the following command:
+There's an option available to run tests with tracing, allowing the test to be
+replayed in the Trace Viewer.
 
 ```shell
-$ pytest --slowmo 1000
+$ pytest --tracing on
+$ playwright show-trace test-results/.../trace.zip
 ```
+### Pytest CLI arguments
+
+Pytest also has some useful CLI arguments
 
 #### Markers
 
-Tests for individual endpoints can be executed using individual markers. For example:
+Some tests are grouped using markers. You can include/exclude groups with the `-m` flag: 
 
 ```shell
 $ pytest -m log_in
+$ pytest -m "not imms_api and not accessibility"
 ```
+#### Parallel test execution
 
-#### Tracing
-
-There's an option available to run tests with tracing, allowing the test to be
-replayed in the Trace Viewer.
+This repository uses [pytest-xdist] to run test modules in parallel. The number of available workers is equal to the number of CPUs that your system has. By default, when running tests locally, all available workers will be used when running multiple test modules. This behaviour can be configured with the `-n` flag.
 
 ```shell
-$ pytest --tracing on
-$ playwright show-trace test-results/.../trace.zip
+$ pytest -n 4    # only use 4 workers
+$ pytest -n 0    # disable pytest-xdist
 ```
 
+[pytest-xdist]:https://github.com/pytest-dev/pytest-xdist
+
 ### Reporting
 
 While the tests are running, results are stored in `allure-results` which can
@@ -123,18 +126,25 @@ $ npx allure-commandline open
 
 ### Linting and formatting
 
-Ruff is used as a linting and formatting tool in this repo:
+[Ruff] is used as a linting and formatting tool in this repo:
 
 ```shell
 $ ruff format
 $ ruff check --fix
 ```
 
+[Ruff]:https://github.com/astral-sh/ruff
+
+### Playwright Page Object Model
+
+The Playwright [Page Object Model] (or POM) approach is taken when developing this repository. Each page/wizard in Mavis should have its own Page object, storing all appropriate locators and methods. When multiple pages use the same locators/methods, a component should be created that extracts these. Then page objects can access this functionality via the component. See `mavis/test/pages/header_component.py` and its usages for an example.
+
+[Page Object Model]:https://playwright.dev/docs/pom
+
 ### More information
 
 Further details on the scope and approach of the automation are on the [NHSD Confluence page](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?spaceKey=Vacc&title=Mavis+Test+Automation).
 
-
 ## Performance tests
 
 ### Installation

mavis/test/pages/programmes.py

@@ -5,7 +5,8 @@
 from playwright.sync_api import Page
 
 from mavis.test.annotations import step
-from mavis.test.constants import Child, DeliverySite, Programme, ReportFormat
+from mavis.test.constants import DeliverySite, Programme, ReportFormat
+from mavis.test.data_models import Child
 from mavis.test.pages.header_component import HeaderComponent
 from mavis.test.utils import get_current_datetime_compact