Unit Testing & Mocks
Relevant source files
The following files were used as context for generating this wiki page:
The Unit Testing & Mocks framework for FLEXT DB Oracle is designed to provide fast, isolated, and deterministic validation of business logic without requiring a live Oracle database. These tests focus on core modules including the API, service facade, domain models, and utility functions, ensuring high code coverage and reliability through the extensive use of mocks and stubs for external dependencies like SQLAlchemy engines or network calls.
Sources: tests/unit/README.md:1-15, tests/README.md:43-51
The suite follows Clean Architecture principles, isolating the domain layer from the infrastructure layer. By simulating database responses and error states, the unit tests verify edge cases such as connection timeouts, configuration validation, and complex DDL generation logic that would otherwise be difficult to trigger consistently in a live environment.
Sources: tests/unit/README.md:21-30, tests/README.md:104-115
Core Testing Architecture
The unit testing layer is the foundation of the project's testing pyramid. It is characterized by sub-second execution times and zero external dependencies, such as filesystem or network access.
This diagram illustrates the isolation of unit tests from the actual database through the use of mocking infrastructure that intercepts calls to external libraries like SQLAlchemy.
Sources: tests/unit/README.md:33-55, tests/README.md:118-130
Mocking Strategy
The project utilizes unittest.mock for isolating external systems. A primary focus is mocking the connection creation and query execution paths.
Connection Mocking
For classes like FlextDbOracleServices, unit tests patch the create_engine call to prevent real network socket initialization. This allows for testing connection lifecycle logic, such as test_connection() and connected(), in a purely local environment.
Sources: tests/unit/test_services.py:16-24, tests/unit/README.md:65-79
Service Layer Mocking
The FlextDbOracleServices tests frequently mock the execute_query method to return SimpleNamespace objects containing pre-defined result data. This is used to validate that the service correctly parses Oracle-specific row structures without a real database.
Sources: tests/unit/test_services.py:186-195
# Example of service layer mocking
execute_result = SimpleNamespace(
failure=False,
error=None,
value=[SimpleNamespace(root={"count": 7})],
)
with patch.object(FlextDbOracleServices, "execute_query", return_value=execute_result):
count_result = service.fetch_table_row_count("test_table", "test_schema")
Sources: tests/unit/test_services.py:196-205
Tested Modules & Components
The following table summarizes the key modules and the focus of their respective unit tests.
| Test Module | Component Tested | Primary Testing Focus |
|---|---|---|
test_api.py | FlextDbOracleApi | Public API surface, factory methods (from_env, from_url), and plugin registration. |
test_services.py | FlextDbOracleServices | SQL building logic (SELECT, INSERT, MERGE), health checks, and Singer type mapping. |
test_models.py | Domain Models | Validation of ConnectionStatus, QueryResult, and Pydantic field constraints. |
test_utilities.py | u.DbOracle | SQL formatting, identifier escaping, and query hash generation. |
test_cli.py | FlextDbOracleClient | CLI preferences, command routing, and error handling without active connections. |
Sources: tests/unit/test_api.py:33-45, tests/unit/test_services.py:34-45, tests/unit/test_models.py:27-42, tests/unit/test_utilities.py:25-35, tests/unit/test_cli.py:31-40
Validation of Logic & Edge Cases
Configuration Validation
Unit tests for FlextDbOracleSettings (within test_models.py and test_services.py) verify that the system rejects invalid ports, empty hosts, and missing credentials. This is performed using Pydantic's model_validate or by manually instantiating settings objects within pytest.raises blocks.
Sources: tests/unit/test_models.py:84-105, tests/unit/test_services.py:483-495
SQL Generation Reliability
The test_services.py module contains extensive tests for the SQL builder. It ensures that identifiers are correctly quoted (e.g., "_SDC_LOADED_AT") while bind names (e.g., :_SDC_LOADED_AT) remain unquoted to satisfy Oracle's syntax requirements.
Sources: tests/unit/test_services.py:151-165
Sources: tests/unit/test_services.py:158-167
Metadata Structure Validation
Tests in test_metadata.py and test_services.py verify the structural integrity of schema objects like Table and Column. Even without a database, these tests ensure that DDL generation for tables with complex primary keys and nullable fields produces the correct string output.
Sources: tests/unit/test_metadata.py:134-150, tests/unit/test_services.py:112-125
Performance & Quality Standards
Unit tests are subject to strict quality gates defined in the project's infrastructure.
- Speed: Every unit test must execute in under 1 second. Sources: tests/README.md:44, tests/unit/README.md:23
- Coverage: The suite aims for high coverage of business logic, including complex type conversions from Singer schemas to Oracle types (e.g., converting "boolean" to
NUMBER(1)). Sources: tests/unit/test_services.py:91-105, tests/README.md:195 - Deterministic Nature: Tests utilize fixed inputs to ensure results are repeatable across different CI/CD environments. Sources: tests/unit/README.md:24
Summary
The Unit Testing & Mocks framework ensures that the core components of FLEXT DB Oracle are robust and logically sound. By isolating code from the Oracle environment, the suite provides developers with immediate feedback on changes to SQL generation, configuration management, and domain models, while maintaining 100% deterministic results across all development environments.