Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for the flext-dbt-oracle project is built upon a multi-tiered approach that emphasizes configuration validation, environmental isolation, and strict governance rules. The project utilizes pytest as its primary test runner, supplemented by a comprehensive suite of quality gates including linting, type checking, and coverage requirements. A core principle of the strategy is that tests must validate configuration and settings changes "by construction," ensuring that the single source of truth (SSOT) remains valid across all test tiers.
Sources: AGENTS.md:14-30, pyproject.toml:346-375, rules.json:140-146
Test Tier Architecture
The project categorizes tests into several distinct tiers, each serving a specific purpose in the validation lifecycle. These tiers are defined within the pyproject.toml configuration and are executed via canonical make verbs.
Tier Definitions
| Tier | Marker | Description |
|---|---|---|
| Unit | unit | Isolated tests for individual components, logic, and configuration parts. |
| Integration | integration | Tests focusing on the interaction between multiple components or systems. |
| E2E | e2e | End-to-end scenarios validating the entire adapter flow. |
| Docker | docker | Tests requiring a live Oracle database container environment. |
| Governance | N/A | Static checks ensuring module structure and coding standards are met. |
Sources: pyproject.toml:358-368, tests/unit/test_module_governance.py:65-98
The following diagram illustrates the flow from code changes through the various validation tiers:
The diagram shows the sequential validation gates a change must pass, starting from static governance to dynamic containerized E2E tests.
Sources: pyproject.toml:358-368, tests/conftest.py:20-56, rules.json:140-146
Configuration Validation Strategy
A significant portion of the testing effort is dedicated to validating FlextDbtOracleSettings. These tests are broken down into construction, connection, and validation parts to ensure that the adapter's configuration is robust and correctly typed.
P0 Rule: Validation by Construction
Tests are strictly prohibited from hardcoding or freezing values that exist in configuration files. Instead, tests must read expected values from the same typed Single Source of Truth (SSOT) that production code uses. This ensures that a legitimate change in a .yaml config file does not break tests unless the change itself is invalid.
Sources: AGENTS.md:14-25
Validation Components
The configuration test suite utilizes inheritance to combine specialized validation logic:
- Construction: Validates default values and basic object instantiation.
- Validation: Ensures numeric ranges, literal types (e.g., materialization types like
tableorview), and required fields are enforced. - Connection: Validates the generation of connection strings and DSNs.
Sources: tests/unit/test_config.py:18-22, tests/unit/_config_parts/validation.py:53-76
Environment and Container Orchestration
To support database-aware testing, the project uses pytest fixtures to manage a shared Oracle container environment.
Docker Control Flow
The docker_control fixture provides a tk instance for container management, while the shared_oracle_container fixture ensures an Oracle instance is active before tests run.
The sequence diagram details how the test suite orchestrates the Oracle database lifecycle and configures the environment variables for the session.
Sources: tests/conftest.py:20-56
Governance and Quality Gates
The strategy includes "Module Governance" tests that enforce architectural constraints through inspection of the package structure.
Governance Rules
- No Module-Level Loggers: Prevents global state by forbidding the definition of
loggerat the module top level. - No Top-Level Functions: Enforces an object-oriented or class-based structure by prohibiting standalone functions in package modules.
Sources: tests/unit/test_module_governance.py:65-98
Quality Gate Thresholds
The project defines strict thresholds for static analysis and coverage. These are integrated into the pyproject.toml and enforced by ruff, mypy, and pytest-cov.
| Tool | Focus | Threshold / Requirement |
|---|---|---|
| Pyright/Mypy | Type Safety | Strict mode; no Any or type: ignore without justification. |
| Coverage | Runtime Path | fail_under = 20 (minimum project-wide baseline). |
| Ruff | Linting | All rules enabled; no hidden defects in tests/ or examples/. |
Sources: pyproject.toml:132-135, pyproject.toml:281-290, AGENTS.md:46-55
Conclusion
The testing strategy for flext-dbt-oracle moves beyond simple functional checks to include architectural governance and configuration robustness. By integrating Docker-based environments for real-world validation and enforcing strict "by construction" configuration rules, the project ensures that the Oracle DBT adapter remains stable across different environments and deployment configurations.
Sources: AGENTS.md:14-30, rules.json:151-157