Updated logic

Author: davethepunkyone

.gitignore

@@ -10,10 +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)
@@ -71,14 +72,42 @@ 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.|
+| 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:
+
+    # 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.
+
+ > NOTE: You should never commit this file or any secrets in the codebase directly.
 
 ## Contributing
 

conftest.py

@@ -15,7 +15,12 @@
 @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.
+    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)