Merge branch 'main' into dependabot/docker/python-3.13-slim

Author: davethepunkyone

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,9 +20,9 @@
 
 <!-- Go over all the following points, and put an `x` in all the boxes that apply. -->
 
-- [ ] I am familiar with the [contributing guidelines](../docs/CONTRIBUTING.md)
+- [ ] I am familiar with the [contributing guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
 - [ ] I have followed the code style of the project
-- [ ] I have added tests to cover my changes
+- [ ] I have added tests to cover my changes (where appropriate)
 - [ ] I have updated the documentation accordingly
 - [ ] This PR is a result of pair or mob programming
 

.vscode/extensions.json

@@ -2,20 +2,20 @@
   "recommendations": [
     "alefragnani.bookmarks",
     "davidanson.vscode-markdownlint",
-    "dbaeumer.vscode-eslint",
     "donjayamanne.githistory",
     "eamodio.gitlens",
     "editorconfig.editorconfig",
-    "esbenp.prettier-vscode",
     "github.codespaces",
     "github.github-vscode-theme",
     "github.remotehub",
     "github.vscode-github-actions",
     "github.vscode-pull-request-github",
     "hediet.vscode-drawio",
+    "howardzuo.vscode-favorites",
     "johnpapa.vscode-peacock",
     "mhutchie.git-graph",
     "ms-azuretools.vscode-docker",
+    "ms-python.python",
     "ms-vscode-remote.remote-containers",
     "ms-vscode-remote.remote-wsl",
     "ms-vscode.hexeditor",

.vscode/settings.json

@@ -3,5 +3,28 @@
     "MD013": false,
     "MD024": { "siblings_only": true },
     "MD033": false
-  }
+  },
+  "cSpell.words": [
+    "addopts",
+    "codegen",
+    "customisable",
+    "customised",
+    "initialise",
+    "Licence",
+    "organisation",
+    "pytest",
+    "pytestmark",
+    "pythonpath",
+    "recognise",
+    "retcode",
+    "ruleset",
+    "utilise",
+    "utilised",
+    "Utilising"
+  ],
+  "python.testing.pytestArgs": [
+    "."
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true
 }

CONTRIBUTING.md

@@ -1,3 +1,40 @@
-# Contributing to this project
+# Contributing To This Project
 
-This page will be populated in the near future to outline the contribution process.
+With this project, we actively encourage anyone who may have any ideas or code that could make this repository better to contribute
+in any way they can.
+
+## How To Contribute
+
+If you have an idea about something new that could be added, then please raise a
+[Feature Request via the Issues tab](https://github.com/nhs-england-tools/playwright-python-blueprint/issues/new/choose) for this
+repository. Even if you don't feel you have the technical ability to implement the request, please raise an issue regardless as
+the maintainers of this project will frequently review any requests and attempt to implement if deemed suitable for this blueprint.
+
+If you have some code you think could be implemented, please raise a Feature Request and
+[create a fork of this repository](https://github.com/nhs-england-tools/playwright-python-blueprint/fork) to experiment and ensure
+that the change you want to push back works as intended.
+
+## Contribution Requirements
+
+For any contributions to this project, the following requirements need to be met:
+
+- You must be a member of the [NHS England Tools](https://github.com/nhs-england-tools) organisation on GitHub.
+- [Any commits must be signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits), so they show as verified once they reach GitHub. This checking serves as part of our CI/CD process, so unsigned commits will prevent a pull request from being merged.
+- For any utility methods that are added to this framework in the `utils` directory, the following applies:
+  - Unit tests for the utility should be added to the `tests_utils` directory and need to be tagged with the `utils` mark.
+  - Documentation for these classes and how to use any methods should also be added to the `docs/utilities-guide` directory.
+  - Each method that is intended to be used as part of a class should have a correctly formatted docstring, to allow for developers using Intellisense within their IDE to understand what the code is intended to do.
+- All CI/CD checks will need to pass before any code is merged to the `main` branch - this includes ensuring appropriate formatting of code and documentation, security checks and that all unit and example tests pass.
+
+## Things We Want
+
+What we are particularly interested in is:
+
+- Any utility classes that can uniformly applied to any project. This may be something that's been created for your own project and by doing some minor abstraction any other teams working in a similar way could adopt this functionality.
+- Any development code that supports executing this project in a CI/CD fashion. This primarily covers any changes that support development principles outlined in the [Software Engineering Quality Framework](https://github.com/NHSDigital/software-engineering-quality-framework), and could include logic around how the test code is containerized.
+- Any changes that allow for test reporting in a consistent, reliable, maintainable and interesting format for varying stakeholders. This includes logic that expands on from the reporting we generate, such as example scripts for how to generate dashboards using the data we generate.
+
+Examples:
+
+- Say you've created a utility for generating test patients within your application. Any elements of this code that could be universally applied and other teams are likely to use (e.g. NHS number, patient name) we would want in this blueprint. If there's something business specific to your project that exists as part of this code (e.g. a unique reference number that only applies to your service), then we would advise removing that logic from any code before raising a pull request here.
+  - If you do end up adding a utility class in this format in a more generic way to this project, you can subsequently [inherit the utility class](https://docs.python.org/3/tutorial/classes.html#inheritance) to include your additional business-specific requirements within your own version of the class.

Makefile

@@ -5,32 +5,4 @@ include scripts/init.mk
 
 # ==============================================================================
 
-# Example CI/CD targets are: dependencies, build, publish, deploy, clean, etc.
-
-dependencies: # Install dependencies needed to build and test the project @Pipeline
-	# TODO: Implement installation of your project dependencies
-
-build: # Build the project artefact @Pipeline
-	# TODO: Implement the artefact build step
-
-publish: # Publish the project artefact @Pipeline
-	# TODO: Implement the artefact publishing step
-
-deploy: # Deploy the project artefact to the target environment @Pipeline
-	# TODO: Implement the artefact deployment step
-
-clean:: # Clean-up project resources (main) @Operations
-	# TODO: Implement project resources clean-up step
-
-config:: # Configure development environment (main) @Configuration
-	# TODO: Use only 'make' targets that are specific to this project, e.g. you may not need to install Node.js
-	make _install-dependencies
-
-# ==============================================================================
-
-${VERBOSE}.SILENT: \
-	build \
-	clean \
-	config \
-	dependencies \
-	deploy \
+# NOTE: This project currently only uses this Makefile as part of CI/CD checks.

README.md

@@ -17,6 +17,7 @@ NOTE: This project is currently under initial development so isn't finalised, bu
     - [Configuration](#configuration)
   - [Getting Started](#getting-started)
   - [Utilities](#utilities)
+  - [Contributing](#contributing)
   - [Contacts](#contacts)
   - [Licence](#licence)
 
@@ -34,6 +35,8 @@ To utilise the blueprint code, you will need to have the following installed:
 
 - [Python](https://www.python.org/downloads/) 3.12 or greater
 
+> NOTE: There are currently known issues with Python 3.13 and Playwright, so if you encounter issues running this project whilst using Python 3.13 it is recommended to downgrade to Python 3.12 in the interim.
+
 Whilst not required to get started, you may also want to [configure a Python virtual environment for your project](https://docs.python.org/3/library/venv.html) 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.
 
@@ -54,6 +57,9 @@ 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](https://code.visualstudio.com/docs/editor/testing) 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.
@@ -74,16 +80,22 @@ This blueprint also provides the following utility classes, that can be used to
 |Utility|Description|
 |-------|-----------|
 |[Axe](./docs/utility-guides/Axe.md)|Accessibility scanning using axe-core.|
-|NHSNumberTools|Basic tools for working with NHS numbers.|
+|[Date Time Utility](./docs/utility-guides/DateTimeUtility.md)|Basic functionality for managing date/times.|
+|[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
+
+Further guidance on contributing to this project can be found in our [contribution](./CONTRIBUTING.md) page.
 
 ## Contacts
 
-If you have any queries regarding this blueprint, please contact [[email protected]](mailto:dave.harding1@nhs.net).
+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.
 
-## Licence
+If you have any general queries regarding this blueprint, please contact [[email protected]](mailto:[email protected]).
 
-> The [LICENCE.md](./LICENCE.md) file will need to be updated with the correct year and owner
+## Licence
 
-Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.
+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.
 
 Any HTML or Markdown documentation is [© Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).