Testing Strategy & Automation
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT DB Oracle implements a comprehensive, multi-layered testing strategy designed to ensure the reliability and performance of Oracle database integrations. The strategy follows Clean Architecture principles, employing unit, integration, and end-to-end (E2E) testing layers to validate everything from isolated business logic to complete system workflows.
The automation framework is built to support high-quality gates, including strict type safety, 90% minimum code coverage, and deterministic execution. By utilizing shared fixtures and standardized assertion patterns, the suite provides fast feedback loops for developers while maintaining enterprise-grade validation for production deployments.
Sources: tests/README.md:21-27, tests/README.md:144-149
## Testing Layers and Architecture
The project utilizes a tiered testing architecture that separates concerns based on execution speed and external dependencies. This ensures that the most critical business logic is tested rapidly in isolation, while complex database interactions are verified in production-like environments.
The diagram shows the relationship between testing layers and their respective execution environments.
Sources: tests/README.md:104-114, tests/unit/README.md:15-20
### Unit Testing (tests/unit/)
Unit tests focus on the isolation of business logic and domain rules. They are designed for maximum speed (typically <1s per test) and have zero external dependencies on networks or filesystems.
- Purpose: Validates input transformation, configuration parsing, and error handling.
- Mechanism: Uses mocks (via
@patch) and stubs to simulate the SQLAlchemy engine and Oracle connection responses. - Key Modules:
test_api.py,test_services.py,test_config.py.
Sources: tests/unit/README.md:23-29, tests/unit/test_services.py:1-12
### Integration Testing (tests/integration/)
Integration tests require a live Oracle database (often managed via Docker) to validate real-world SQL execution and schema introspection.
- Focus: Connection pooling, transaction management (commit/rollback), and Oracle-specific metadata extraction.
- Data Management: Uses dedicated test schemas to ensure isolation between concurrent test runs.
Sources: tests/integration/README.md:21-26, tests/integration/README.md:46-52
### End-to-End Testing (tests/e2e/)
E2E tests validate complete user journeys from the CLI or high-level API down to the database persistence layer.
- Scope: Full system integration, including plugin lifecycles and observability metrics.
- Realism: Mirror actual usage patterns using realistic business data (e.g., customers and orders tables).
Sources: tests/e2e/README.md:18-24, tests/e2e/README.md:144-150
## Test Execution and Configuration
Test execution is standardized through make commands and environment variable configurations. This allows for both local development "fail-fast" loops and exhaustive CI/CD validation.
### Test Commands
| Command | Layer | Description |
|---|---|---|
pytest tests/unit/ | Unit | Runs fast, isolated tests with mocks. |
pytest tests/integration/ | Integration | Runs tests requiring a real Oracle connection. |
pytest -m "not slow" | All | Executes only fast-running tests by filtering markers. |
make test | All | Standard command for full suite execution with coverage. |
Sources: tests/README.md:124-132
### Environment Variables for Database Testing
To execute integration and E2E tests, the following configuration must be exported to the shell:
export ORACLE_INTEGRATION_TESTS=1
export FLEXT_TARGET_ORACLE_HOST=localhost
export FLEXT_TARGET_ORACLE_PORT=1521
export FLEXT_TARGET_ORACLE_SERVICE_NAME=XEPDB1
export FLEXT_TARGET_ORACLE_USERNAME=test_user
export FLEXT_TARGET_ORACLE_PASSWORD=test_password
Sources: tests/README.md:136-143, tests/integration/README.md:79-85
## Standards and Quality Gates
The project enforces strict "Universal Agent Laws" and engineering principles to ensure test code remains maintainable and accurate.
- Zero-Tolerance Policy: Root causes must be fixed and validated in the same turn; no "dead code" or workarounds are permitted.
- Naming Convention:
test_<method>_<scenario>_<expected_result>. For example:test_connect_with_valid_config_returns_success. - Coverage Gates: Minimum 90% code coverage across all modules, verified via
pytest-cov. - Assertion Patterns: Standardized use of
tm(flext-tests) for consistent validation ofr[T]results (Railway-oriented programming).
The sequence shows the standard workflow for code validation before landing changes.
Sources: AGENTS.md:27-38, tests/README.md:164-168, tests/README.md:180-188
## Mocking Strategy
Unit tests utilize a specific mocking strategy to simulate Oracle interactions without the overhead of a database. This is primarily seen in the FlextDbOracleServices and FlextDbOracleApi tests.
@patch("flext_db_oracle.connection.create_engine")
def test_connection_with_mocked_engine(mock_create_engine):
"""Test connection creation with mocked SQLAlchemy engine."""
# Arrange
mock_engine = Mock()
mock_create_engine.return_value = mock_engine
# Act
connection = FlextDbOracleConnection(settings)
result = connection.connect()
# Assert
assert result.success
mock_create_engine.assert_called_once()
Sources: tests/unit/README.md:58-72
## Conclusion
The testing strategy for FLEXT DB Oracle ensures a balance between developer productivity and system reliability. By enforcing strict quality gates and separating tests into logical layers (Unit, Integration, E2E), the project maintains a high degree of confidence in its Oracle integration capabilities. Automation through Docker-based environments and standardized CI/CD pipelines ensures that every change is validated against real-world database behaviors.
Sources: tests/README.md:225-228