Python Unit Testing
Relevant source files
The following files were used as context for generating this wiki page:
Python unit testing within the flext-dbt-oracle-wms project is a rigorous quality gate designed to validate configuration, behavior contracts, and public API surfaces. The project adheres to a "P0" rule where tests must validate configuration changes by construction, ensuring that expected values are read from a single source of truth (SSOT) rather than being hardcoded.
The testing architecture leverages pytest and a suite of specialized plugins to enforce type safety, coverage, and performance. Unit tests specifically target the core facade (Simple API), CLI service logic, and module governance to ensure all public entry points remain functional and properly typed.
Sources: AGENTS.md:14-25, pyproject.toml:162-185, tests/unit/test_simple_api.py:1-5
Testing Infrastructure and Governance
The project utilizes pytest as its primary testing framework, configured with numerous plugins to manage environments, mocks, and coverage. Module governance tests verify that primary classes and entry points are importable and callable, maintaining the integrity of the package exports.
Test Tooling Configuration
The testing environment is defined in pyproject.toml, specifying dependencies and execution parameters.
| Tool/Plugin | Purpose |
|---|---|
pytest | Core testing framework (minimum version 8.4). |
pytest-cov | Measures code coverage with a fail-under threshold of 20%. |
pytest-mock | Provides mocking utilities for isolating unit tests. |
pytest-xdist | Enables parallel test execution. |
flext-tests | Internal library providing testing utilities (tm, tf, td). |
Sources: pyproject.toml:94-118, pyproject.toml:162-185, tests/unit/test_module_governance.py:1-18
Governance Validation Flow
Governance tests ensure the structural integrity of the codebase.
The diagram shows the sequence of checks performed to validate that the project's public interface is correctly exposed.
Sources: tests/unit/test_module_governance.py:11-18
Unit Test Architecture
Unit tests are organized into specific suites targeting different layers of the application: the Simple API (facade) and the CLI Service. These tests frequently use "mock" clients and services that implement the project's internal protocols.
Simple API Testing
Tests for the FlextDbtOracleWms class focus on validating that the facade correctly interacts with its internal client and service components. This includes testing connectivity, entity discovery, and the full WMS-to-DBT pipeline.
This diagram illustrates how unit tests verify the coordination between the facade and its injected dependencies during a pipeline run.
Sources: tests/unit/test_simple_api.py:114-143
CLI Service Testing
The FlextDbtOracleWmsCliService tests ensure that command-line arguments are correctly parsed and routed to the underlying facade. This includes handling default entity names (e.g., defaulting to "inventory" if no entity is specified for extraction) and managing exit codes.
| CLI Command | Test Scenario | Expected Outcome |
|---|---|---|
info (empty) | Run with no arguments | Exit Code 0 |
discover | Valid discovery call | Exit Code 0 |
extract | Missing entity name | Defaults to "inventory", Exit Code 0 |
pipeline | Underlying failure | Exit Code 1 |
Sources: tests/unit/test_cli.py:84-135
Mocking and Protocols
Unit tests extensively use local mock classes (e.g., _SuccessfulConnectionClient, _WorkflowClient, _CliService) to simulate external WMS and DBT interactions without requiring live environments. These mocks implement protocols defined in the core project.
Implementation Patterns
Mocks are often defined with @override decorators to satisfy type-checking requirements while providing controlled return values (using the Result pattern).
class _SuccessfulConnectionClient(FlextDbtOracleWmsClient):
@override
def test_oracle_wms_connection(self) -> p.Result[m.Dict]:
return r[m.Dict].ok(
m.Dict.model_validate({
"status": "connected",
"base_url": "https://wms.example.com",
}),
)
Sources: tests/unit/test_simple_api.py:17-26, tests/unit/test_cli.py:19-53
Summary
Python Unit Testing in flext-dbt-oracle-wms serves as a critical verification layer that ensures the reliability of the WMS-to-DBT transformation logic. By employing strict behavior contracts and SSOT-driven configuration validation, the testing suite guarantees that both the programmatic API and the CLI interface remain stable during ongoing development and configuration updates.