Merge branch 'main' of github.com:NHSDigital/bcss-playwright into feature/BCSS-20435-oracle-util-markdown-doc

Author: adrianoaru-nhs

.gitignore

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

.vscode/extensions.json

@@ -15,13 +15,15 @@
     "johnpapa.vscode-peacock",
     "mhutchie.git-graph",
     "ms-azuretools.vscode-docker",
+    "ms-python.black-formatter",
     "ms-python.python",
     "ms-vscode-remote.remote-containers",
     "ms-vscode-remote.remote-wsl",
     "ms-vscode.hexeditor",
     "ms-vscode.live-server",
     "ms-vsliveshare.vsliveshare",
     "redhat.vscode-xml",
+    "sonarsource.sonarlint-vscode",
     "streetsidesoftware.code-spell-checker-british-english",
     "tamasfe.even-better-toml",
     "tomoki1207.pdf",

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

@@ -4,7 +4,7 @@ pytest-json-report>=1.5.0
 pytest-playwright-axe>=4.10.3
 oracledb~=3.0.0
 pandas~=2.2.3
-python-dotenv~=1.0.1
+python-dotenv~=1.1.0
 sqlalchemy>=2.0.38
 jproperties~=2.1.2
 pypdf>=5.3.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()

utils/axe.py

@@ -6,7 +6,6 @@
 
 
 logger = logging.getLogger(__name__)
-
 PATH_FOR_REPORT = Path(os.getcwd()) / "axe-reports"
 
 

utils/user_tools.py

@@ -1,4 +1,5 @@
 import json
+import os
 import logging
 import os
 from pathlib import Path
@@ -7,7 +8,7 @@
 from pages.login.cognito_login_page import CognitoLoginPage
 
 logger = logging.getLogger(__name__)
-USERS_FILE = Path(__file__).parent.parent / "users.json"
+USERS_FILE = Path(os.getcwd()) / "users.json"
 
 
 class UserTools: