README Update (#14)

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

<!-- Describe your changes in detail. -->
This initially populates the README with information that is relevant to
getting started with this project.

## Context

<!-- Why is this change required? What problem does it solve? -->
The initial information copied from the template was confusing and
didn't actually do anything with 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. -->

- [ ] I am familiar with the [contributing
guidelines](../docs/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [ ] I have added tests to cover my changes
- [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: davethepunkyone

LICENCE.md

@@ -1,6 +1,6 @@
 # MIT Licence
 
-Copyright (c) 2023 Crown Copyright NHS England.
+Copyright (c) 2024 Crown Copyright NHS England.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,118 +1,78 @@
 # Playwright Python Blueprint
 
-[![CI/CD Pull Request](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=repository-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=repository-template)
+[![CI/CD Pull Request](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/playwright-python-blueprint/actions/workflows/cicd-1-pull-request.yaml)
 
 This project is designed to provide a blueprint to allow for development teams to start quickly developing UI tests using [Playwright Python](https://playwright.dev/python/), providing the base framework and utilities to allow for initial focus on writing tests, rather than configuration of the framework itself.
 
 NOTE: This project is currently under initial development.
 
+> **NOTE: When considering this project, please be advised that currently Playwright is a "proposed" tool within the [NHS England Tech Radar](https://radar.engineering.england.nhs.uk/).  Whilst we are taking steps to get Playwright moved to the "mainstream" section of the radar, as it has not yet been formally adopted it is possible that Playwright may not be fully endorsed by NHS England as a standard tool going forward and using this framework for an NHS England project is at your own risk.**
+
 ## Table of Contents
 
 - [Playwright Python Blueprint](#playwright-python-blueprint)
   - [Table of Contents](#table-of-contents)
   - [Setup](#setup)
     - [Prerequisites](#prerequisites)
     - [Configuration](#configuration)
-  - [Usage](#usage)
-    - [Testing](#testing)
-  - [Design](#design)
-    - [Diagrams](#diagrams)
-    - [Modularity](#modularity)
-  - [Contributing](#contributing)
+  - [Getting Started](#getting-started)
   - [Contacts](#contacts)
   - [Licence](#licence)
 
 ## Setup
 
-By including preferably a one-liner or if necessary a set of clear CLI instructions we improve user experience. This should be a frictionless installation process that works on various operating systems (macOS, Linux, Windows WSL) and handles all the dependencies.
-
-Clone the repository
+You can clone this whole repository using the code below:
 
 ```shell
-git clone https://github.com/nhs-england-tools/repository-template.git
-cd nhs-england-tools/repository-template
+git clone https://github.com/nhs-england-tools/playwright-python-blueprint.git
 ```
 
-### Prerequisites
-
-The following software packages, or their equivalents, are expected to be installed and configured:
+The code for actually working in Playwright is contained in the blueprint directory, so it's best to do the following to move straight into that working directory:
 
-- [Docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [Podman](https://podman.io/),
-- [asdf](https://asdf-vm.com/) version manager,
-- [GNU make](https://www.gnu.org/software/make/) 3.82 or later,
+```shell
+cd nhs-england-tools/playwright-python-blueprint/blueprint
+```
 
-> [!NOTE]<br>
-> The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [Homebrew](https://brew.sh/) installed, then to install `make`, like so:
->
-> ```shell
-> brew install make
-> ```
->
-> You will then see instructions to fix your [`$PATH`](https://github.com/nhs-england-tools/dotfiles/blob/main/dot_path.tmpl) variable to make the newly installed version available. If you are using [dotfiles](https://github.com/nhs-england-tools/dotfiles), this is all done for you.
+### Prerequisites
 
-- [GNU sed](https://www.gnu.org/software/sed/) and [GNU grep](https://www.gnu.org/software/grep/) are required for the scripted command-line output processing,
-- [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation,
+To utilise the blueprint code, you will need to have the following installed:
 
-> [!NOTE]<br>
-> For macOS users, installation of the GNU toolchain has been scripted and automated as part of the `dotfiles` project. Please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details.
+- [Python](https://www.python.org/downloads/) 3.12 or greater
 
-- [Python](https://www.python.org/) required to run Git hooks,
-- [`jq`](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor.
+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.
 
 ### Configuration
 
-Installation and configuration of the toolchain dependencies
+To get started using Playwright and with the examples provided, use the following commands:
 
 ```shell
-make config
+pip install -r requirements.txt
+playwright install --with-deps
 ```
 
-## Usage
-
-After a successful installation, provide an informative example of how this project can be used. Additional code snippets, screenshots and demos work well in this space. You may also link to the other documentation resources, e.g. the [User Guide](./docs/user-guide.md) to demonstrate more use cases and to show more features.
+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):
 
-### Testing
-
-There are `make` tasks for you to configure to run your tests.  Run `make test` to see how they work.  You should be able to use the same entry points for local development as in your CI pipeline.
-
-## Design
-
-### Diagrams
-
-The [C4 model](https://c4model.com/) is a simple and intuitive way to create software architecture diagrams that are clear, consistent, scalable and most importantly collaborative. This should result in documenting all the system interfaces, external dependencies and integration points.
-
-![Repository Template](./docs/diagrams/Repository_Template_GitHub_Generic.png)
-
-The source for diagrams should be in Git for change control and review purposes. Recommendations are [draw.io](https://app.diagrams.net/) (example above in [docs](.docs/diagrams/) folder) and [Mermaids](https://github.com/mermaid-js/mermaid). Here is an example Mermaids sequence diagram:
-
-```mermaid
-sequenceDiagram
-    User->>+Service: GET /users?params=...
-    Service->>Service: auth request
-    Service->>Database: get all users
-    Database-->>Service: list of users
-    Service->>Service: filter users
-    Service-->>-User: list[User]
+```shell
+pytest --tracing on --headed
 ```
 
-### Modularity
+## Getting Started
 
-Most of the projects are built with customisability and extendability in mind. At a minimum, this can be achieved by implementing service level configuration options and settings. The intention of this section is to show how this can be used. If the system processes data, you could mention here for example how the input is prepared for testing - anonymised, synthetic or live data.
+> 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.
 
-## Contributing
+Once you've confirmed your installation is working, please take a look at the following guides on getting started with Playwright Python.
 
-Describe or link templates on how to raise an issue, feature request or make a contribution to the codebase. Reference the other documentation files, like
+1. [Understanding Playwright Python](./docs/getting-started/1_Understanding_Playwright_Python.md)
+2. [Blueprint File Breakdown](./docs/getting-started/2_Blueprint_File_Breakdown.md)
 
-- Environment setup for contribution, i.e. `CONTRIBUTING.md`
-- Coding standards, branching, linting, practices for development and testing
-- Release process, versioning, changelog
-- Backlog, board, roadmap, ways of working
-- High-level requirements, guiding principles, decision records, etc.
+For additional reading and guidance on writing tests, we also recommend reviewing the [Playwright Python documentation](https://playwright.dev/python/docs/writing-tests).
 
 ## Contacts
 
-Provide a way to contact the owners of this project. It can be a team, an individual or information on the means of getting in touch via active communication channels, e.g. opening a GitHub discussion, raising an issue, etc.
+If you have any queries regarding this blueprint, please contact [[email protected]](mailto:[email protected]).
 
 ## Licence
 

blueprint/pytest.ini

@@ -7,6 +7,7 @@ addopts =
     --json-report
     --json-report-file=test-results/results.json
     --json-report-omit=collectors
+    --tracing=retain-on-failure
 markers =
     example: tests used for example purposes
     branch: tests designed to run at a branch level

blueprint/tests/test_example.py

@@ -25,9 +25,8 @@ def test_basic_example(page: Page) -> None:
 
     This test does the following:
     1) Navigates to this repository
-    2) Asserts that the README contents rendered by GitHub includes the text "Playwright Python Blueprint"
-    3) Clicks the MIT license link
-    4) Asserts that the LICENCE contents rendered by GitHub includes the text "MIT Licence"
+    2) Asserts that the README contents rendered by GitHub contains the text "Playwright Python Blueprint"
+    3) Asserts that the main section of the page contains the topic label "playwright-python"
     '''
 
     # Navigate to page
@@ -36,11 +35,8 @@ def test_basic_example(page: Page) -> None:
     # Assert repo text is present
     expect(page.get_by_role("article")).to_contain_text("Playwright Python Blueprint")
 
-    # Click license link
-    page.get_by_role("link", name="MIT license", exact=True).click()
-
-    # Assert license text
-    expect(page.get_by_role("article")).to_contain_text("MIT Licence")
+    # Assert the page loaded is the playwright-python topic page
+    expect(page.get_by_role("main")).to_contain_text("playwright-python")
 
 
 @pytest.mark.example

docs/getting-started/1_Understanding_Playwright_Python.md

@@ -0,0 +1 @@
+# Getting Started #1: Understanding Playwright Python

docs/getting-started/2_Blueprint_File_Breakdown.md

@@ -0,0 +1 @@
+# Getting Started #2: Blueprint File Breakdown