Env File Support (#52)

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

<!-- Describe your changes in detail. -->
This adds functionality to support .env files for sensitive values,
including a new script to automatically generate a local.env file and a
fixture to run before all tests within the project and populate
environment variables from this file when code is running.

## Context

<!-- Why is this change required? What problem does it solve? -->
This allows for anyone using this framework to store sensitive values
locally for testing purposes, without the need of saving or committing
any values to the codebase.

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

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

- [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: davethepunkyone

.gitignore

@@ -10,9 +10,12 @@
 *.code-workspace
 !project.code-workspace
 
-# Please, add your custom content below!
+# Specific to this blueprint
 
 __pycache__/
 .pytest_cache/
 test-results/
 axe-reports/
+local.env
+
+# Please, add your custom content below!

README.md

@@ -15,6 +15,7 @@ This project is designed to provide a blueprint to allow for development teams t
     - [Configuration](#configuration)
   - [Getting Started](#getting-started)
   - [Utilities](#utilities)
+  - [Using Environment Variables For Secrets](#using-environment-variables-for-secrets)
   - [Contributing](#contributing)
   - [Contacts](#contacts)
   - [Licence](#licence)
@@ -33,8 +34,6 @@ 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.
 
@@ -73,14 +72,44 @@ For additional reading and guidance on writing tests, we also recommend reviewin
 
 ## Utilities
 
-This blueprint also provides the following utility classes, that can be used to aid in testing:
+This blueprint provides the following utility classes, that can be used to aid in testing:
+
+| Utility                                                       | Description                                  |
+| ------------------------------------------------------------- | -------------------------------------------- |
+| [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](./docs/utility-guides/NHSNumberTools.md)     | Basic tools for working with NHS numbers.    |
+| [User Tools](./docs/utility-guides/UserTools.md)              | Basic user management tool.                  |
+
+## Using Environment Variables For Secrets
+
+This blueprint provides functionality for saving secret / sensitive values that you would not want present
+in the codebase, but require to execute tests locally (such as passwords or API keys).  A local.env file can
+be generated by running the [following script](./setup_env_file.py):
+
+```shell
+python ./setup_env_file.py
+```
+
+This script file is design to be amended / updated as your project evolves, so as more sensitive values are required
+for executing tests, the list of keys provided can be updated so for subsequent runs of the script, all the expected
+keys are populated within the local.env file (which will need their values setting manually). The intent is that this
+script can be run to onboard new team members and provide a local file with all the variables they need to populate.
+
+The local.env file (if present), is read at the start of any test session (via the [conftest.py file](./conftest.py))
+and any variables can be accessed by using the Python os library like so:
+
+```python
+# Import the OS library
+import os
+
+# Access environment variable
+os.getenv('<key_from_local.env>')
+```
+
+The local.env file is set in the [.gitignore file](./.gitignore), so by default it will not commit if amended.
 
-|Utility|Description|
-|-------|-----------|
-|[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](./docs/utility-guides/NHSNumberTools.md)|Basic tools for working with NHS numbers.|
-|[User Tools](./docs/utility-guides/UserTools.md)|Basic user management tool.|
+ > NOTE: You should never commit this file or any secrets in the codebase directly.
 
 ## Contributing
 

conftest.py

@@ -0,0 +1,26 @@
+"""
+This is a conftest.py file for pytest, which is used to set up fixtures and hooks for testing.
+This file is used to define fixtures that can be used across multiple test files.
+It is also used to define hooks that can be used to modify the behavior of pytest.
+"""
+
+import pytest
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+
+LOCAL_ENV_PATH = Path(os.getcwd()) / 'local.env'
+
+
+@pytest.fixture(autouse=True, scope="session")
+def import_local_env_file() -> None:
+    """
+    This fixture is used to import the local.env file into the test environment (if the file is present),
+    and will populate the environment variables prior to any tests running.
+    If environment variables are set in a different way when running (e.g. via cli), this will
+    prioritise those values over the local.env file.
+
+    NOTE: You should not use this logic to read a .env file in a pipeline or workflow to set sensitive values.
+    """
+    if Path.is_file(LOCAL_ENV_PATH):
+        load_dotenv(LOCAL_ENV_PATH, override=False)

requirements.txt

@@ -2,3 +2,4 @@ pytest-playwright>=0.5.1
 pytest-html>=4.1.1
 pytest-json-report>=1.5.0
 pytest-playwright-axe>=4.10.3
+python-dotenv>=1.1.0

setup_env_file.py

@@ -0,0 +1,30 @@
+"""
+This script creates a local.env file that can be used to populate secrets such as passwords or API keys
+locally. This is useful for local development and testing, as it allows you to keep sensitive information
+out of your codebase.
+
+This is designed to be generated when setting up this project, so if new variables are required, these
+should be added to the REQUIRED_KEYS list below to automatically populate the local.env file with the
+keys required to run this project.
+"""
+
+import os
+from pathlib import Path
+
+REQUIRED_KEYS = ["USER_PASS"]
+DEFAULT_LOCAL_ENV_PATH = Path(os.getcwd()) / 'local.env'
+
+def create_env_file():
+    """
+    Create a local.env file with the required keys.
+    """
+    with open(DEFAULT_LOCAL_ENV_PATH, 'w') as f:
+        f.write("# Use this file to populate secrets without committing them to the codebase (as this file is set in .gitignore).\n")
+        f.write("# To retrieve values as part of your tests, use os.getenv('VARIABLE_NAME').\n")
+        f.write("# Note: When running in a pipeline or workflow, you should pass these variables in at runtime.\n\n")
+        for key in REQUIRED_KEYS:
+            f.write(f'{key}=\n')
+
+
+if __name__ == "__main__":
+    create_env_file()