Repository: NHSDigital/bcss-playwright
Pull request #53: Adding markdown document and docstrings for Load Properties Util
Author: login: adrianoaru-nhs
Labels: name: documentation
description: Improvements or additions to documentation
Created: 2025-05-08T08:11:29Z | Merged: 2025-05-08T08:41:09Z

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

<!-- Describe your changes in detail. -->
Updating docstrings for the load properties util to be inline with the contribution guidelines.
Creating a markdown doc for this util to explain how it works.

## Context

<!-- Why is this change required? What problem does it solve? -->
Ensuring the code follows the contribution guidelines.

## 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.



Diff:
diff --git a/docs/utility-guides/LoadProperties.md b/docs/utility-guides/LoadProperties.md
new file mode 100644
index 00000000..9fb338c3
--- /dev/null
+++ b/docs/utility-guides/LoadProperties.md
@@ -0,0 +1,49 @@
+# Utility Guide: Load Properties
+
+The Load Properties Utility can be used to retrieve values from a properties file.
+
+## Table of Contents
+
+- [Utility Guide: Load Properties](#utility-guide-load-properties)
+  - [Table of Contents](#table-of-contents)
+  - [How This Works](#how-this-works)
+  - [Using the Load Properties Utility](#using-the-load-properties-utility)
+  - [Example usage](#example-usage)
+
+## How This Works
+
+This utility uses the `jproperties` package to load the properties files.<br>
+There is a class `PropertiesFile`, containing the locations of both files:
+
+1. `self.smokescreen_properties_file`: tests/smokescreen/bcss_smokescreen_tests.properties
+2. `self.general_properties_file`: tests/bcss_tests.properties
+
+The method `get_properties()` will load either one of these based on the input provided.<br>
+To ensure that there are no mistakes when providing this input there are two additional methods to call that will do this for you:
+
+1. `get_smokescreen_properties()`: Which will load `self.smokescreen_properties_file`
+2. `get_general_properties()`: Which will load `self.general_properties_file`
+
+To add values to the properties file follow the format:
+
+    # ----------------------------------
+    # EXAMPLE VALUES
+    # ----------------------------------
+    example_value_1=value1
+    example_value_2=value2
+
+## Using the Load Properties Utility
+
+To use this utility in a test reference the pytest fixture in `conftest.py`.<br>
+There is no need to import anything as any fixtures in `conftest.py` will be automatically discovered by pytest.
+Here there are two fixtures:
+
+1. `smokescreen_properties` - which is used to load the file: tests/smokescreen/bcss_smokescreen_tests.properties
+2. `get_general_properties` - which is used to load the file: tests/bcss_tests.properties
+
+## Example usage
+
+    def test_example_1(page: Page, general_properties: dict) -> None:
+        print(
+            general_properties["example_value_1"]
+        )
diff --git a/utils/load_properties_file.py b/utils/load_properties_file.py
index 35ebf88e..2764411d 100644
--- a/utils/load_properties_file.py
+++ b/utils/load_properties_file.py
@@ -2,35 +2,44 @@
 import os
 
 
-class PropertiesFile():
+class PropertiesFile:
     def __init__(self):
-        self.smokescreen_properties_file = "tests/smokescreen/bcss_smokescreen_tests.properties"
+        self.smokescreen_properties_file = (
+            "tests/smokescreen/bcss_smokescreen_tests.properties"
+        )
         self.general_properties_file = "tests/bcss_tests.properties"
 
-
     def get_properties(self, type_of_properties_file: str | None = None) -> dict:
         """
         Reads the 'bcss_smokescreen_tests.properties' file or 'bcss_tests.properties' and populates a 'Properties' object depending on whether "smokescreen" is given
         Returns a dictionary of properties for use in tests.
 
+        Args:
+            type_of_properties_file (str): The type of properties file you want to load. e.g. 'smokescreen' or 'general'
+
         Returns:
             dict: A dictionary containing the values loaded from the 'bcss_smokescreen_tests.properties' file.
         """
         configs = Properties()
-        path =  f"{os.getcwd()}/{self.smokescreen_properties_file if type_of_properties_file == "smokescreen" else self.general_properties_file}"
-        with open(
-            path, "rb"
-            ) as read_prop:
+        path = f"{os.getcwd()}/{self.smokescreen_properties_file if type_of_properties_file == "smokescreen" else self.general_properties_file}"
+        with open(path, "rb") as read_prop:
             configs.load(read_prop)
         return configs.properties
 
-
     def get_smokescreen_properties(self) -> dict:
-        "This is used to get the `tests/smokescreen/bcss_smokescreen_tests.properties` file"
-        return self.get_properties("smokescreen")
+        """
+        This is used to get the `tests/smokescreen/bcss_smokescreen_tests.properties` file
 
+        Returns:
+            dict: A dictionary containing the values loaded from the 'bcss_smokescreen_tests.properties' file.
+        """
+        return self.get_properties("smokescreen")
 
     def get_general_properties(self) -> dict:
-        "This is used to get the `tests/bcss_tests.properties` file"
-        return self.get_properties()
+        """
+        This is used to get the `tests/bcss_tests.properties` file
 
+        Returns:
+            dict: A dictionary containing the values loaded from the 'bcss_smokescreen_tests.properties' file.
+        """
+        return self.get_properties()


Reviews:
user: login: Andyg79
state: COMMENTED
author_association: NONE
submitted_at: 2025-05-08T08:26:52Z
user: login: Andyg79
state: DISMISSED
author_association: NONE
submitted_at: 2025-05-08T08:36:09Z
user: login: Andyg79
state: APPROVED
author_association: NONE
submitted_at: 2025-05-08T08:38:06Z

Review comments:
diff_hunk: @@ -0,0 +1,49 @@
+# Utility Guide: Load Properties
+
+The Load Properties Utility can be used to retrieve values from a properties file.
+
+## Table of Contents
+
+- [Utility Guide: Load Properties](#utility-guide-load-properties)
+  - [Table of Contents](#table-of-contents)
+  - [How This Works](#how-this-works)
+  - [Using the Load Properties Utility](#using-the-load-properties-utility)
+  - [Example usage](#example-usage)
+
+## How This Works
+
+This utility uses the `jproperties` package to load the properties files.<br>
+There is a class `PropertiesFile`, containing the locations of both files:
+
+1. `self.smokescreen_properties_file`: tests/smokescreen/bcss_smokescreen_tests.properties
+2. `self.general_properties_file`: tests/bcss_tests.properties
+
+The method `get_properties()` will load either one of these based on the input provided.<br>
+To ensure that there are no mistakes when providing this input there are two additional methods to call that will do this for you:
+
+1. `get_smokescreen_properties()`: Which will load `self.smokescreen_properties_file`
+2. `get_general_properties()`: Which will load `self.general_properties_file`
+
+To add values to the properties file follow the format:
+
+    # ----------------------------------
+    # EXAMPLE VALUES
+    # ----------------------------------
+    example_value_1=value1
+    example_value_2=value2
+
+## Using the Load Properties Utility
+
+To use the this utility in a test reference the pytest fixture in `conftest.py`.<br>
path: docs/utility-guides/LoadProperties.md
user: login: Andyg79
body: Is the word 'the' redundant?
e.g. should it be 'To use this utility'?
created_at: 2025-05-08T08:21:14Z
author_association: NONE
diff_hunk: @@ -2,35 +2,44 @@
 import os
 
 
-class PropertiesFile():
+class PropertiesFile:
     def __init__(self):
-        self.smokescreen_properties_file = "tests/smokescreen/bcss_smokescreen_tests.properties"
+        self.smokescreen_properties_file = (
+            "tests/smokescreen/bcss_smokescreen_tests.properties"
+        )
         self.general_properties_file = "tests/bcss_tests.properties"
 
-
     def get_properties(self, type_of_properties_file: str | None = None) -> dict:
         """
         Reads the 'bcss_smokescreen_tests.properties' file or 'bcss_tests.properties' and populates a 'Properties' object depending on whether "smokescreen" is given
         Returns a dictionary of properties for use in tests.
 
+        Args:
+            type_of_properties_file (str): the type of properties file you want to load. E.g. 'smokescreen' or 'general'
+
path: utils/load_properties_file.py
user: login: Andyg79
body: Very minor, but should this be e.g. instead of E.g.?
created_at: 2025-05-08T08:23:29Z
author_association: NONE

PR comments:
user: login: sonarqubecloud[bot]
created_at: 2025-05-08T08:37:28Z
body: ## [![Quality Gate Passed](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/checks/QualityGateBadge/qg-passed-20px.png 'Quality Gate Passed')](https://sonarcloud.io/dashboard?id=NHSDigital_bcss-playwright&pullRequest=53) **Quality Gate passed**  
Issues  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 New issues](https://sonarcloud.io/project/issues?id=NHSDigital_bcss-playwright&pullRequest=53&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/accepted-16px.png '') [0 Accepted issues](https://sonarcloud.io/project/issues?id=NHSDigital_bcss-playwright&pullRequest=53&issueStatuses=ACCEPTED)

Measures  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 Security Hotspots](https://sonarcloud.io/project/security_hotspots?id=NHSDigital_bcss-playwright&pullRequest=53&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Coverage on New Code](https://sonarcloud.io/component_measures?id=NHSDigital_bcss-playwright&pullRequest=53&metric=new_coverage&view=list)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Duplication on New Code](https://sonarcloud.io/component_measures?id=NHSDigital_bcss-playwright&pullRequest=53&metric=new_duplicated_lines_density&view=list)  
  
[See analysis details on SonarQube Cloud](https://sonarcloud.io/dashboard?id=NHSDigital_bcss-playwright&pullRequest=53)


author_association: NONE