Additional doc updates

Author: davethepunkyone

.vscode/settings.json

@@ -7,6 +7,8 @@
   "cSpell.words": [
     "addopts",
     "codegen",
+    "customisable",
+    "customised",
     "initialise",
     "Licence",
     "organisation",

README.md

@@ -78,7 +78,8 @@ This blueprint also provides the following utility classes, that can be used to
 |-------|-----------|
 |[Axe](./docs/utility-guides/Axe.md)|Accessibility scanning using axe-core.|
 |[Date Time Utility](./docs/utility-guides/DateTimeUtility.md)|Basic functionality for managing date/times.|
-|NHSNumberTools|Basic tools for working with NHS numbers.|
+|[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
 

docs/getting-started/2_Blueprint_File_Breakdown.md

@@ -9,6 +9,7 @@ This guide outlines the breakdown of this blueprint, and specifically the files
   - [Directories \& Files Directly Impacting Tests](#directories--files-directly-impacting-tests)
     - [`requirements.txt`](#requirementstxt)
     - [`pytest.ini`](#pytestini)
+    - [`users.json`](#usersjson)
     - [`tests/`](#tests)
     - [`pages/`](#pages)
     - [`utils/`](#utils)
@@ -36,6 +37,11 @@ This file outlines the configuration of pytest, and ultimately how Playwright al
 
 Any configuration you want to apply to all of your test executions should be placed in this file where possible, to ensure easy maintenance.
 
+### `users.json`
+
+This file outlines the users you may want to use as part of your testing, and is utilised by the User Tools utility. Further information on how this file is used
+can be found in the [User Tools Utility Guide](../utility-guides/UserTools.md).
+
 ### `tests/`
 
 This directory is designed to house all of your tests intended for execution.
@@ -66,3 +72,4 @@ The following directories and files are specific for this repository, and may re
 - `scripts/`: This directory houses the scripts used by this repository, primarily as part of the CI/CD checks.
 - `tests_utils/`: This directory houses the unit tests for the utilities provided by this repository. You may want to copy these over if you want to ensure utilities are behaving as expected.
 - `.editorconfig`, `.gitattributes`, `.gitignore`, `.gitleaks.toml`, `.gitleaksignore`: These files are configuration for git, and quality and security checks provided via the CI/CD checks.
+- `Makefile`: This file is used to import some of the scripts for CI/CD checks, but can be customised per project if needed. The template this project is based from provides a more comprehensive example [here](https://github.com/nhs-england-tools/repository-template/blob/main/Makefile).

docs/utility-guides/NHSNumberTools.md

@@ -0,0 +1,39 @@
+# Utility Guide: NHS Number Tools
+
+The NHS Number Tools utility provided by this blueprint allows for the easy management of NHS numbers, and provides
+common functionality that may apply to many services in relation to NHS Number management.
+
+## Table of Contents
+
+- [Utility Guide: NHS Number Tools](#utility-guide-nhs-number-tools)
+  - [Table of Contents](#table-of-contents)
+  - [Using the NHS Number Tools class](#using-the-nhs-number-tools-class)
+  - [`spaced_nhs_number()`: Return Spaced NHS Number](#spaced_nhs_number-return-spaced-nhs-number)
+    - [Required Arguments](#required-arguments)
+    - [Returns](#returns)
+
+## Using the NHS Number Tools class
+
+You can initialise the NHS Number Tools class by using the following code in your test file:
+
+    from utils.nhs_number_tools import NHSNumberTools
+
+## `spaced_nhs_number()`: Return Spaced NHS Number
+
+The `spaced_nhs_number()` method is designed to take the provided NHS number and return it in a formatted
+string of the format `nnn nnn nnnn`.  It's a static method so can be used in the following way:
+
+    # Return formatted NHS number
+    spaced_nhs_number = NHSNumberTools.spaced_nhs_number("1234567890")
+
+### Required Arguments
+
+The following are required for `NHSNumberTools.spaced_nhs_number()`:
+
+| Argument   | Format         | Description               |
+| ---------- | -------------- | ------------------------- |
+| nhs_number | `str` or `int` | The NHS number to format. |
+
+### Returns
+
+A `str` with the provided NHS number in `nnn nnn nnnn` format. For example, `NHSNumberTools.spaced_nhs_number(1234567890)` would return `123 456 7890`.

docs/utility-guides/UserTools.md

@@ -9,6 +9,11 @@ at the base of the repository.
   - [Table of Contents](#table-of-contents)
   - [Using the User Tools class](#using-the-user-tools-class)
   - [Managing Users](#managing-users)
+    - [Considering Security](#considering-security)
+  - [`retrieve_user()`: Retrieve User Details](#retrieve_user-retrieve-user-details)
+    - [Required Arguments](#required-arguments)
+    - [Returns](#returns)
+    - [Example Usage](#example-usage)
 
 ## Using the User Tools class
 
@@ -32,3 +37,53 @@ For example, adding a record like so (this example shows the entire `users.json`
             "unique_id": 42
         }
     }
+
+The data you require for these users can be completely customised for what information you need, so whilst the example shows `username`, `roles`
+and `unique_id` as possible values we may want to use, this is not an exhaustive list. The key that is used (so in this example, `"Documentation User"`)
+is also customisable and should be how you want to easily reference retrieving this user in your tests.
+
+### Considering Security
+
+An important note on managing users in this way is that passwords or security credentials should **never** be stored in the `users.json` file. These
+are considered secrets, and whilst it may be convenient to store them in this file, it goes against the
+[security principles outlined in the Software Engineering Quality Framework](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/security.md#application-level-security).
+
+With this in mind, it's recommended to do the following when it comes to managing these types of credentials:
+
+- When running locally, store any secret values in a local configuration file and set this file in `.gitignore` so it is not committed to the codebase.
+- When running via a CI/CD process, store any secret values in an appropriate secret store and pass the values into pytest at runtime.
+
+## `retrieve_user()`: Retrieve User Details
+
+The `retrieve_user()` method is designed to easily retrieve the data for a specific user entry from the `users.json` file. This is a static method,
+so can be called using the following logic:
+
+    # Retrieving documentation user details from example
+    user_details = UserTools.retrieve_user("Documentation User")
+
+### Required Arguments
+
+The following are required for `UserTools.retrieve_user()`:
+
+| Argument | Format | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| user     | `str`  | The key from `users.json` for the user details required |
+
+### Returns
+
+A Python `dict` object that contains the values associated with the provided user argument.
+
+### Example Usage
+
+When using a `users.json` file as set up in the example above:
+
+    from utils.user_tools import UserTools
+    from playwright.sync_api import Page
+
+    def test_login(page: Page) -> None:
+        # Retrieving documentation user details from example
+        user_details = UserTools.retrieve_user("Documentation User")
+
+        # Use values to populate a form
+        page.get_by_role("textbox", name="Username").fill(user_details["username"])
+        page.get_by_role("textbox", name="ID").fill(user_details["unique_id"])

tests_utils/test_user_tools.py

@@ -9,13 +9,13 @@
 def test_retrieve_user(monkeypatch: object) -> None:
     monkeypatch.setattr(utils.user_tools, "USERS_FILE", Path(__file__).parent / "resources" / "test_users.json")
 
-    test_user = UserTools().retrieve_user("Test User")
+    test_user = UserTools.retrieve_user("Test User")
     assert test_user["username"] == "TEST_USER1"
     assert test_user["test_key"] == "TEST A"
 
-    test_user2 = UserTools().retrieve_user("Test User 2")
+    test_user2 = UserTools.retrieve_user("Test User 2")
     assert test_user2["username"] == "TEST_USER2"
     assert test_user2["test_key"] == "TEST B"
 
     with pytest.raises(UserToolsException, match=r'User \[Invalid User\] is not present in users.json'):
-        UserTools().retrieve_user("Invalid User")
+        UserTools.retrieve_user("Invalid User")