Added date_time utility, unit tests, and utility guide. (#33)

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

<!-- Added date_time utility to enable easy manipulation/formatting of
datetime elements. Included unit tests, and a utility guide giving an
overview of how to use the function. -->

## Context

<!-- The change is required so that teams utilising the framework will
have a function to assist them in writing tests as quickly as possible
-->

## 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. -->

- [ ] I am familiar with the [contributing
guidelines](../docs/CONTRIBUTING.md)
- [x ] I have followed the code style of the project
- [x] I have added tests to cover my changes
- [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: Andyg79

docs/utility-guides/DateTimeUtility.md

@@ -0,0 +1,22 @@
+# Utility Guide: Date Time Utility
+
+The Date Time Utility can be used to manipulate dates and times for various purposes,
+such as asserting timestamp values, changing the format of a date, or returning the day of the week for a given date.
+
+## Using the Date Time Utility
+
+To use the Date Time Utility, import the 'DateTimeUtils' class into your test file and then call the DateTimeUtils
+functions from within your tests, as required.
+
+## Required arguments
+
+The functions in this class require different arguments, including `datetime`, `str`, and `float`.
+Look at the docstrings for each function to see what arguments are required.
+The docstrings also specify when arguments are optional, and what the default values are when no argument is provided.
+
+## Example usage
+
+    from tests_utils.date_time_utils import DateTimeUtils
+
+        def test_date_format(page: Page) -> None:
+        expect(page.locator("#date")).to_contain_text(DateTimeUtils.current_datetime()))

tests_utils/test_date_time_utils.py

@@ -0,0 +1,45 @@
+from datetime import datetime, timedelta
+import utils.date_time_utils
+
+
+def test_current_datetime():
+    dtu = utils.date_time_utils.DateTimeUtils()
+    current_date = datetime.now()
+    current_date1 = current_date.strftime("%d/%m/%Y %H:%M")
+    current_date2 = current_date.strftime("%Y-%m-%d %H:%M")
+    current_date3 = current_date.strftime("%d %B %Y %H:%M")
+    assert dtu.current_datetime() == current_date.strftime("%d/%m/%Y %H:%M")
+    assert dtu.current_datetime("%Y-%m-%d %H:%M") == current_date.strftime("%Y-%m-%d %H:%M")
+    assert dtu.current_datetime("%d %B %Y %H:%M") == current_date.strftime("%d %B %Y %H:%M")
+
+
+def test_format_date():
+    dtu = utils.date_time_utils.DateTimeUtils()
+    date = datetime(2022, 12, 31)
+    formatted_date1 = dtu.format_date(date, "%d/%m/%Y")
+    formatted_date2 = dtu.format_date(date, "%Y/%m/%d")
+    formatted_date3 = dtu.format_date(date, "%d %B %Y")
+    assert dtu.format_date(date, "%d/%m/%Y") == "31/12/2022"
+    assert dtu.format_date(date, "%Y/%m/%d") == "2022/12/31"
+    assert dtu.format_date(date, "%d %B %Y") == "31 December 2022"
+
+
+def test_add_days():
+    dtu = utils.date_time_utils.DateTimeUtils()
+    date = datetime.now()
+    new_date = dtu.add_days(date, 5)
+    assert new_date == date + timedelta(days=5)
+
+
+def test_get_day_of_week_for_today():
+    dtu = utils.date_time_utils.DateTimeUtils()
+    date = datetime.now()
+    day_of_week = dtu.get_a_day_of_week(date)
+    assert day_of_week in ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
+
+
+def test_get_a_day_of_week():
+    dtu = utils.date_time_utils.DateTimeUtils()
+    date = datetime(2023, 11, 8)
+    day_of_week = dtu.get_a_day_of_week(date)
+    assert day_of_week in ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]

utils/date_time_utils.py

@@ -0,0 +1,73 @@
+from datetime import datetime, timedelta
+
+
+class DateTimeUtils:
+    def __init__(self):
+        pass
+
+    @staticmethod
+    def current_datetime(format_date: str = "%d/%m/%Y %H:%M") -> str:
+        """Gets the current datetime in the specified format.
+
+        Args:
+            format_date (str): [Optional] The format to return the current datetime in. Defaults to dd/mm/yyyy hh:mm if not provided.
+
+        Returns:
+            current_date (str): The current datetime in the specified format.
+
+        """
+        return datetime.now().strftime(format_date)
+
+    @staticmethod
+    def format_date(date: datetime, format_date: str = "%d/%m/%Y") -> str:
+        """Formats a specified datetime object.
+
+        Args:
+            date (datetime): The date to be formatted.
+            format_date (str): [Optional] The format to return the datetime in. Defaults to dd/mm/yyyy if not provided.
+
+        Returns:
+            format_date (str): The formatted date in the specified format.
+
+            """
+        return date.strftime(format_date)
+
+    @staticmethod
+    def add_days(date: datetime, days: float) -> datetime:
+        """Adds a specified number of days to a specified date.
+
+        Args:
+            date (datetime): The date to which the days will be added.
+            days (float): The number of days to add to the specified date.
+
+        Returns:
+            new_date (datetime): The specified date plus the number of specified days (year, month, day, hour, minute, second, microsecond).
+
+            """
+        return date + timedelta(days=days)
+
+    @staticmethod
+    def get_day_of_week_for_today(date: datetime) -> str:
+        """Gets the day of the week (e.g., Monday, Tuesday) from the specified date.
+
+        Args:
+            date (datetime): The current date using the now function
+
+        Returns:
+            day_of_week (str): The day of the week relating to the specified date.
+
+            """
+        return date.strftime("%A")
+
+    @staticmethod
+    def get_a_day_of_week(date: datetime) -> str:
+        """Gets the day of the week (e.g., Monday, Tuesday) from the specified date.
+
+        Args:
+            date (datetime): The date for which the day of the week will be returned.
+
+        Returns:
+            day_of_week (str): The day of the week relating to the specified date.
+
+            """
+        return date.strftime("%A")