Addressing feedback comments from reviews (#90)

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

<!-- Describe your changes in detail. -->
Changing the markdown comment to address feedback given during reviews.

## Context

<!-- Why is this change required? What problem does it solve? -->
Makes it easier to understand when and how to use the utility.

## 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)
- [ ] 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. -->

- [x] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [ ] I have added tests to cover my changes (where appropriate)
- [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: adrianoaru-nhs

docs/utility-guides/UserTools.md

@@ -1,6 +1,6 @@
 # Utility Guide: User Tools
 
-The User Tools utility provided by this blueprint allows for the easy management of test users via a json file included
+The User Tools utility provided by this blueprint allows for the easy management of test users via a `users.json` file included
 at the base of the repository.
 
 ## Table of Contents
@@ -10,56 +10,85 @@ at the base of the repository.
   - [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)
+  - [`user_login()`: Log In as a User](#user_login-log-in-as-a-user)
     - [Required Arguments](#required-arguments)
-    - [Returns](#returns)
     - [Example Usage](#example-usage)
+  - [`retrieve_user()`: Retrieve User Details](#retrieve_user-retrieve-user-details)
+    - [Required Arguments](#required-arguments-1)
+    - [Returns](#returns)
+    - [Example Usage](#example-usage-1)
 
 ## Using the User Tools class
 
-You can initialise the User Tools class by using the following code in your test file:
+You can use the User Tools class by importing it in your test file:
 
-    from utils.user_tools import UserTools
+```python
+from utils.user_tools import UserTools
+```
 
 This module has been designed as a static class, so you do not need to instantiate it when you want to retrieve any user information.
 
 ## Managing Users
 
-For this class, users are managed via the [users.json](../../users.json) file provided with this repository. For any new users you need to
-add, the idea is to just add a new record, with any appropriate metadata you need for the user whilst they interact with your application.
+For this class, users are managed via the [`users.json`](../../users.json) file provided with this repository. For any new users you need to add, simply add a new record with any appropriate metadata you need for the user whilst they interact with your application.
 
 For example, adding a record like so (this example shows the entire `users.json` file):
 
-    {
-        "Documentation User": {
-            "username": "DOC_USER",
-            "roles": ["Example Role A"],
-            "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.
+```json
+{
+    "Hub Manager State Registered at BCS01": {
+        "username": "BCSS401",
+        "roles": [
+            "Hub Manager State Registered, Midlands and North West"
+        ]
+  }
+}
+```
 
 ### 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
+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 locally, store any secret values in a local configuration file such as `local.env`. This file is created by running the script [`setup_env_file.py`](../../setup_env_file.py) and is included 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.
 
+## `user_login()`: Log In as a User
+
+The `user_login()` method allows you to log in to the BCSS application as a specified user. It retrieves the username from the `users.json` file and the password from the `local.env` file (using the `BCSS_PASS` environment variable).
+
+### Required Arguments
+
+| Argument  | Format | Description                                                        |
+|-----------|--------|--------------------------------------------------------------------|
+| page      | `Page` | The Playwright page object to interact with.                       |
+| username  | `str`  | The key from `users.json` for the user you want to log in as.      |
+
+### Example Usage
+
+```python
+from utils.user_tools import UserTools
+
+def test_login_as_user(page):
+    UserTools.user_login(page, "Hub Manager State Registered at BCS01")
+```
+
+> **Note:**
+> Ensure you have set the `BCSS_PASS` environment variable in your `local.env` file (created by running `setup_env_file.py`) before using this method.
+
+---
+
 ## `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")
+```python
+# Retrieving documentation user details from example
+user_details = UserTools.retrieve_user("Hub Manager State Registered at BCS01")
+```
 
 ### Required Arguments
 
@@ -77,13 +106,18 @@ A Python `dict` object that contains the values associated with the provided use
 
 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
+```python
+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("Hub Manager State Registered at BCS01")
+
+    # Use values to populate a form
+    page.get_by_role("textbox", name="Username").fill(user_details["username"])
+```
 
-    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"])
+For more details on each function's implementation, refer to the source code in `utils/user_tools.py`.