orionis 0.282.0__py3-none-any.whl → 0.284.0__py3-none-any.whl

orionis/test/exceptions/test_persistence_error.py

@@ -0,0 +1,34 @@
+class OrionisTestPersistenceError(Exception):
+    """
+    Custom exception for persistence errors in tests within the Orionis framework.
+
+    This exception is used to indicate issues related to data persistence during test execution,
+    providing a descriptive message to help identify and resolve the error.
+
+    Args:
+        msg (str): A descriptive message explaining the cause of the persistence error.
+
+    Example:
+        raise OrionisTestPersistenceError("Failed to save test state to the database.")
+    """
+
+    def __init__(self, msg: str):
+        """
+        Initializes the OrionisTestConfigException with a specific error message.
+
+        Args:
+            msg (str): A descriptive error message explaining the cause of the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Returns a formatted string representation of the exception.
+
+        The string includes the exception name and the error message, providing
+        a clear and concise description of the issue.
+
+        Returns:
+            str: A formatted string describing the exception.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/exceptions/test_runtime_error.py

@@ -0,0 +1,26 @@
+class OrionisTestRuntimeError(Exception):
+    """
+    Exception raised for errors that occur during the runtime of Orionis tests.
+    This exception is intended to provide a clear and descriptive error message
+    when a runtime error is encountered in the Orionis testing framework.
+    Attributes:
+    Example:
+        raise OrionisTestRuntimeError("An unexpected runtime error occurred during testing.")
+    """
+
+    def __init__(self, msg: str):
+        """
+        Initializes the exception with a given error message.
+        Args:
+            msg (str): The error message describing the runtime error.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the exception, including the class name and the first argument.
+
+        Returns:
+            str: A string in the format '<ClassName>: <first argument>'.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/exceptions/test_value_error.py

@@ -0,0 +1,26 @@
+class OrionisTestValueError(Exception):
+    """
+    Custom exception class for handling value errors in the Orionis test framework.
+    This exception should be raised when a value-related error occurs during testing.
+    It provides a formatted string representation that includes the class name and the error message.
+    Example:
+        raise OrionisTestValueError("Invalid value provided.")
+    """
+
+    def __init__(self, msg: str):
+        """
+        Initializes the exception with a custom error message.
+
+        Args:
+            msg (str): The error message describing the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the exception, including the class name and the first argument.
+
+        Returns:
+            str: A formatted string in the form 'ClassName: message'.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"

orionis/test/logs/contracts/history.py

@@ -0,0 +1,54 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional, Tuple
+
+class ITestHistory(ABC):
+
+    @abstractmethod
+    def create(self, report: Dict) -> bool:
+        """
+        Create a new test report in the history database.
+
+        Parameters
+        ----------
+        report : Dict
+            A dictionary containing the test report data.
+
+        Returns
+        -------
+        bool
+            True if the report was successfully created, False otherwise.
+        """
+        pass
+
+    def reset(self) -> bool:
+        """
+        Reset the history database by dropping the existing table.
+
+        Returns
+        -------
+        bool
+            True if the database was successfully reset, False otherwise.
+        """
+        pass
+
+    def get(
+        self,
+        first: Optional[int] = None,
+        last: Optional[int] = None
+    ) -> List[Tuple]:
+        """
+        Retrieve test reports from the history database.
+
+        Parameters
+        ----------
+        first : Optional[int], default=None
+            The number of earliest reports to retrieve, ordered ascending by ID.
+        last : Optional[int], default=None
+            The number of latest reports to retrieve, ordered descending by ID.
+
+        Returns
+        -------
+        List[Tuple]
+            A list of tuples representing the retrieved reports.
+        """
+        pass

orionis/test/logs/history.py

@@ -0,0 +1,372 @@
+import json
+import re
+import sqlite3
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+from orionis.services.environment.env import Env
+from orionis.test.exceptions.test_persistence_error import OrionisTestPersistenceError
+from orionis.test.exceptions.test_value_error import OrionisTestValueError
+from orionis.test.logs.contracts.history import ITestHistory
+
+class TestHistory(ITestHistory):
+
+    def __init__(
+        self,
+        storage_path: Optional[str] = None,
+        db_name: Optional[str] = 'tests.sqlite',
+        table_name: Optional[str] = 'reports',
+    ) -> None:
+        """
+        Initialize the history storage for test logs.
+
+        Parameters
+        ----------
+        storage_path : Optional[str], default=None
+            Directory path where the database file will be stored. If not provided,
+            the path is determined from the TEST_DB_PATH environment variable or
+            defaults to 'orionis/test/logs/storage' in the current working directory.
+        db_name : Optional[str], default='tests.sqlite'
+            Name of the SQLite database file. Must be alphanumeric or underscore and
+            end with '.sqlite'.
+        table_name : Optional[str], default='reports'
+            Name of the table to use in the database. Must be alphanumeric or underscore.
+
+        Raises
+        ------
+        OrionisTestValueError
+            If db_name or table_name do not meet the required format.
+        """
+
+        # Validate db_name: only alphanumeric and underscores, must end with .sqlite
+        if not isinstance(db_name, str) or not re.fullmatch(r'[a-zA-Z0-9_]+\.sqlite', db_name):
+            raise OrionisTestValueError("Database name must be alphanumeric/underscore and end with '.sqlite'.")
+        self.__db_name = db_name
+
+        # Validate table_name: only alphanumeric and underscores
+        if not isinstance(table_name, str) or not re.fullmatch(r'[a-zA-Z0-9_]+', table_name):
+            raise OrionisTestValueError("Table name must be alphanumeric/underscore only.")
+        self.__table_name = table_name
+
+        # Determine database path
+        db_path = None
+        if storage_path:
+            db_path = Path(storage_path).expanduser().resolve()
+            if db_path.is_dir():
+                db_path = db_path / self.__db_name
+        else:
+            env_path = Env.get(key="TEST_DB_PATH", default=None, is_path=True)
+            if env_path:
+                db_path = Path(env_path).expanduser().resolve()
+                if db_path.is_dir():
+                    db_path = db_path / self.__db_name
+            else:
+                db_path = Path.cwd() / 'storage/framework/testing' / self.__db_name
+
+        # Ensure parent directory exists
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Store path in environment
+        Env.set(key="TEST_DB_PATH", value=str(db_path), is_path=True)
+        self.__db_path = db_path
+
+        # Create a connection to the database, initially set to None
+        self._conn: Optional[sqlite3.Connection] = None
+
+    def __connect(self) -> None:
+        """
+        Establishes a connection to the SQLite database if not already connected.
+
+        Attempts to create a new SQLite connection using the provided database path.
+        If the connection fails, raises an OrionisTestPersistenceError with the error details.
+
+        Raises
+        ------
+        OrionisTestPersistenceError
+            If a database connection error occurs.
+        """
+        if self._conn is None:
+            try:
+                self._conn = sqlite3.connect(str(self.__db_path))
+            except (sqlite3.Error, Exception) as e:
+                raise OrionisTestPersistenceError(f"Database connection error: {e}")
+            finally:
+                self._conn = None
+
+    def __createTableIfNotExists(self) -> bool:
+        """
+        Ensures that the test history table exists in the database.
+
+        Connects to the database and creates the table with the required schema if it does not already exist.
+        Handles any SQLite errors by rolling back the transaction and raising a custom exception.
+
+        Raises
+        ------
+        OrionisTestPersistenceError
+            If the table creation fails due to a database error.
+
+        Returns
+        -------
+        bool
+            True if the table was created successfully or already exists, False otherwise.
+        """
+
+        self.__connect()
+        try:
+            cursor = self._conn.cursor()
+            cursor.execute(f'''
+                CREATE TABLE IF NOT EXISTS {self.__table_name} (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    json TEXT NOT NULL,
+                    total_tests INTEGER,
+                    passed INTEGER,
+                    failed INTEGER,
+                    errors INTEGER,
+                    skipped INTEGER,
+                    total_time REAL,
+                    success_rate REAL,
+                    timestamp TEXT
+                )
+            ''')
+            self._conn.commit()
+            return True
+        except sqlite3.Error as e:
+            if self._conn:
+                self._conn.rollback()
+            raise OrionisTestPersistenceError(f"Failed to create table: {e}")
+        finally:
+            if self._conn:
+                self.__close()
+                self._conn = None
+
+    def __insertReport(self, report: Dict) -> bool:
+        """
+        Inserts a test report into the history database table.
+
+        Parameters
+        ----------
+        report : Dict
+            A dictionary containing the report data. Must include the following keys:
+            - total_tests
+            - passed
+            - failed
+            - errors
+            - skipped
+            - total_time
+            - success_rate
+            - timestamp
+
+        Raises
+        ------
+        OrionisTestPersistenceError
+            If there is an error inserting the report into the database.
+        OrionisTestValueError
+            If required fields are missing from the report.
+
+        Returns
+        -------
+        bool
+            True if the report was successfully inserted, False otherwise.
+        """
+
+        # Required fields in the report
+        fields = [
+            "json", "total_tests", "passed", "failed", "errors",
+            "skipped", "total_time", "success_rate", "timestamp"
+        ]
+
+        # Validate report structure
+        missing = []
+        for key in fields:
+            if key not in report:
+                missing.append(key)
+        if missing:
+            raise OrionisTestValueError(f"Missing report fields: {missing}")
+
+        # Insert the report into the database
+        self.__connect()
+        try:
+
+            # Query to insert the report into the table
+            query = f'''
+                INSERT INTO {self.__table_name} (
+                    json, total_tests, passed, failed, errors,
+                    skipped, total_time, success_rate, timestamp
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            '''
+
+            # Execute the insert query with the report data
+            cursor = self._conn.cursor()
+            cursor.execute(query, (
+                json.dumps(report),
+                report["total_tests"],
+                report["passed"],
+                report["failed"],
+                report["errors"],
+                report["skipped"],
+                report["total_time"],
+                report["success_rate"],
+                report["timestamp"]
+            ))
+            self._conn.commit()
+            return True
+        except sqlite3.Error as e:
+            if self._conn:
+                self._conn.rollback()
+            raise OrionisTestPersistenceError(f"Failed to insert report: {e}")
+        finally:
+            if self._conn:
+                self.__close()
+                self._conn = None
+
+    def __getReports(
+        self,
+        first: Optional[int] = None,
+        last: Optional[int] = None
+    ) -> List[Tuple]:
+        """
+        Retrieves a specified number of report records from the database, ordered by their ID.
+
+        Parameters
+        ----------
+        first : Optional[int], default=None
+            The number of earliest reports to retrieve, ordered ascending by ID.
+        last : Optional[int], default=None
+            The number of latest reports to retrieve, ordered descending by ID.
+
+        Returns
+        -------
+        List[Tuple]
+            A list of tuples representing the report records.
+
+        Raises
+        ------
+        OrionisTestValueError
+            If both 'first' and 'last' are specified, or if either is not a positive integer.
+        OrionisTestPersistenceError
+            If there is an error retrieving reports from the database.
+        """
+
+        # Validate parameters
+        if first is not None and last is not None:
+            raise OrionisTestValueError(
+                "Cannot specify both 'first' and 'last' parameters. Use one or the other."
+            )
+        if first is not None:
+            if not isinstance(first, int) or first <= 0:
+                raise OrionisTestValueError("'first' must be an integer greater than 0.")
+        if last is not None:
+            if not isinstance(last, int) or last <= 0:
+                raise OrionisTestValueError("'last' must be an integer greater than 0.")
+
+        order = 'DESC' if last is not None else 'ASC'
+        quantity = first if first is not None else last
+
+        self.__connect()
+        try:
+            cursor = self._conn.cursor()
+            query = f"SELECT * FROM {self.__table_name} ORDER BY id {order} LIMIT ?"
+            cursor.execute(query, (quantity,))
+            results = cursor.fetchall()
+            return results
+        except sqlite3.Error as e:
+            raise OrionisTestPersistenceError(f"Failed to retrieve reports from '{self.__db_name}': {e}")
+        finally:
+            if self._conn:
+                self.__close()
+                self._conn = None
+
+    def __resetDatabase(self) -> bool:
+        """
+        Resets the database by dropping the existing table.
+        This method connects to the database, drops the table specified by
+        `self.__table_name` if it exists, commits the changes, and then closes
+        the connection. If an error occurs during the process, an
+        OrionisTestPersistenceError is raised.
+
+        Raises
+        ------
+        OrionisTestPersistenceError
+            If the database reset operation fails due to an SQLite error.
+
+        Returns
+        -------
+        bool
+            True if the database was successfully reset, False otherwise.
+        """
+
+        self.__connect()
+        try:
+            cursor = self._conn.cursor()
+            cursor.execute(f'DROP TABLE IF EXISTS {self.__table_name}')
+            self._conn.commit()
+            return True
+        except sqlite3.Error as e:
+            raise OrionisTestPersistenceError(f"Failed to reset database: {e}")
+        finally:
+            if self._conn:
+                self.__close()
+                self._conn = None
+
+    def __close(self) -> None:
+        """
+        Closes the current database connection.
+        This method checks if a database connection exists. If so, it closes the connection and sets the connection attribute to None.
+
+        Returns
+        -------
+        None
+        """
+
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def create(self, report: Dict) -> bool:
+        """
+        Create a new test report in the history database.
+
+        Parameters
+        ----------
+        report : Dict
+            A dictionary containing the test report data.
+
+        Returns
+        -------
+        bool
+            True if the report was successfully created, False otherwise.
+        """
+        self.__createTableIfNotExists()
+        return self.__insertReport(report)
+
+    def reset(self) -> bool:
+        """
+        Reset the history database by dropping the existing table.
+
+        Returns
+        -------
+        bool
+            True if the database was successfully reset, False otherwise.
+        """
+        return self.__resetDatabase()
+
+    def get(
+        self,
+        first: Optional[int] = None,
+        last: Optional[int] = None
+    ) -> List[Tuple]:
+        """
+        Retrieve test reports from the history database.
+
+        Parameters
+        ----------
+        first : Optional[int], default=None
+            The number of earliest reports to retrieve, ordered ascending by ID.
+        last : Optional[int], default=None
+            The number of latest reports to retrieve, ordered descending by ID.
+
+        Returns
+        -------
+        List[Tuple]
+            A list of tuples representing the retrieved reports.
+        """
+        return self.__getReports(first, last)

orionis/test/output/contracts/dumper.py

@@ -3,27 +3,43 @@ from abc import ABC, abstractmethod
 class ITestDumper(ABC):
     """
     Interface for standard output debugging utilities.
-    This interface defines methods for dumping debugging information, capturing the caller's file, method, and line number, and utilizing a Debug class to output the information. Implementations should provide mechanisms to output or log the provided arguments for debugging purposes
+
+    This interface defines methods for dumping debugging information,
+    capturing the caller's file, method, and line number, and utilizing
+    a Debug class to output the information.
+
+    Implementations
+    --------------
+    Implementations should provide mechanisms to output or log the
+    provided arguments for debugging purposes.
     """
 
     @abstractmethod
-    def dd(self, *args):
+    def dd(self, *args) -> None:
         """
         Dumps debugging information using the Debug class.
-        This method captures the caller's file, method, and line number,
+
+        This method captures the caller's file and line number,
         and uses the Debug class to output debugging information.
-        Args:
-            *args: Variable length argument list to be dumped.
+
+        Parameters
+        ----------
+        *args : tuple
+            Variable length argument list to be dumped.
         """
         pass
 
     @abstractmethod
-    def dump(self, *args):
+    def dump(self, *args) -> None:
         """
         Dumps debugging information using the Debug class.
+
         This method captures the caller's file, method, and line number,
         and uses the Debug class to output debugging information.
-        Args:
-            *args: Variable length argument list to be dumped.
+
+        Parameters
+        ----------
+        *args : tuple
+            Variable length argument list to be dumped.
         """
         pass

orionis/test/output/dumper.py

@@ -1,27 +1,46 @@
 import os
 import sys
+from orionis.test.exceptions.test_runtime_error import OrionisTestRuntimeError
 from orionis.test.output.contracts.dumper import ITestDumper
 
 class TestDumper(ITestDumper):
     """
     TestDumper provides utility methods for debugging and outputting information during test execution.
-    This class implements methods to determine if an object is a test case instance and to output debugging
-    information using the Debug class. It ensures that standard output and error streams are properly managed
-    during debugging dumps, and captures the caller's file and line number for context.
+
+    This class implements methods to:
+        - Determine if an object is a test case instance.
+        - Output debugging information using the Debug class.
+        - Manage standard output and error streams during debugging dumps.
+        - Capture the caller's file and line number for context.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    __isTestCaseClass(value)
+        Determines if the given value is an instance of a test case class.
+    dd(*args)
+        Dumps debugging information using the Debug class.
+    dump(*args)
+        Dumps debugging information using the Debug class.
     """
 
-    def __isTestCaseClass(self, value):
+    def __isTestCaseClass(self, value) -> bool:
         """
-        Determines if the given value is an instance of a test case class.
-        This method checks whether the provided value is an instance of one of the
-        predefined test case classes: AsyncTestCase, TestCase, or SyncTestCase.
-        If the value is None or an ImportError occurs during the import of the
-        test case classes, the method returns False.
-        Args:
-            value: The object to be checked.
-        Returns:
-            bool: True if the value is an instance of AsyncTestCase, TestCase,
-            or SyncTestCase; False otherwise.
+        Check if the given value is an instance of a test case class.
+
+        Parameters
+        ----------
+        value : object
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if `value` is an instance of AsyncTestCase, TestCase, or SyncTestCase;
+            False otherwise.
         """
         try:
             if value is None:
@@ -33,13 +52,17 @@ class TestDumper(ITestDumper):
         except Exception:
             return False
 
-    def dd(self, *args):
+    def dd(self, *args) -> None:
         """
         Dumps debugging information using the Debug class.
-        This method captures the caller's file, method, and line number,
+
+        This method captures the caller's file and line number,
         and uses the Debug class to output debugging information.
-        Args:
-            *args: Variable length argument list to be dumped.
+
+        Parameters
+        ----------
+        *args : tuple
+            Variable length argument list to be dumped.
         """
         if not args:
             return
@@ -62,17 +85,23 @@ class TestDumper(ITestDumper):
                 dumper.dd(*args[1:])
             else:
                 dumper.dd(*args)
+        except Exception as e:
+            raise OrionisTestRuntimeError(f"An error occurred while dumping debug information: {e}")
         finally:
             sys.stdout = original_stdout
             sys.stderr = original_stderr
 
-    def dump(self, *args):
+    def dump(self, *args) -> None:
         """
         Dumps debugging information using the Debug class.
+
         This method captures the caller's file, method, and line number,
         and uses the Debug class to output debugging information.
-        Args:
-            *args: Variable length argument list to be dumped.
+
+        Parameters
+        ----------
+        *args : tuple
+            Variable length argument list to be dumped.
         """
         if not args:
             return
@@ -95,6 +124,8 @@ class TestDumper(ITestDumper):
                 dumper.dump(*args[1:])
             else:
                 dumper.dump(*args)
+        except Exception as e:
+            raise OrionisTestRuntimeError(f"An error occurred while dumping debug information: {e}")
         finally:
             sys.stdout = original_stdout
             sys.stderr = original_stderr