Merge branch 'main' into feature/BCSS-20441-tableutil-markdown-doc-and-doc-strings

Author: mepr1

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"]
+        )

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()