Testing Strategy Overview

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• tests/README.md
• tests/conftest.py
• tests/integration/test_oracle.py
• tests/unit/test_target.py
• tests/performance/test_performance.py
• tests/unit/test_loader.py
• tests/unit/test_module_governance.py
• pyproject.toml

The testing strategy for flext-target-oracle is designed to ensure the reliability and performance of Singer-compatible data loading into Oracle databases. The strategy follows a multi-tiered approach, leveraging pytest for unit, integration, and end-to-end testing, alongside performance benchmarks and automated module governance. A key pillar of this strategy is the automated management of Oracle Express Edition (XE) containers via Docker, ensuring that tests requiring a real database are consistent and reproducible.

The framework utilizes Railway-Oriented Programming (ROP) patterns (via the r result type) for error handling and strict type checking with mypy and pyrefly. Testing infrastructure is centralized in the tests/ directory, supported by a comprehensive set of fixtures in conftest.py that handle container lifecycles, database connectivity, and mock environments.

Sources: CONTRIBUTING.md:46-51, tests/README.md:1-20, pyproject.toml:290-315

Test Tier Architecture

The project categorizes tests into four distinct tiers, each with specific requirements and execution triggers. This isolation allows developers to run fast unit tests frequently while reserving resource-intensive database tests for final verification.

Classification Table

Tier	Directory	Marker	Requirement	Description
Unit	tests/unit/	unit	None	Fast tests mocking all external dependencies (Oracle API).
Integration	tests/integration/	integration	Oracle DB	Tests actual SQL execution, DDL/DML, and schema mappings.
End-to-End	tests/e2e/	e2e	Oracle DB	Full Singer workflows from schema initialization to state updates.
Performance	tests/performance/	performance	Oracle DB	Benchmarks for bulk insert throughput and latency.

Sources: tests/README.md:38-52, CONTRIBUTING.md:53-62, pyproject.toml:290-315

Tier Execution Flow

The following diagram illustrates the typical developer workflow and how the different test tiers interact with external resources.

Infrastructure and Automation

Oracle Container Management

Integration and E2E tests automatically manage an Oracle XE container lifecycle. The shared_oracle_container session fixture (defined in conftest.py) handles the orchestration:

1. tk shared controller: Provides Docker control using the flext-oracle-db-test identifier.
2. Health Checks: The fixture waits up to 180 seconds for Oracle to become ready.
3. User Provisioning: It automatically creates the FLEXT_TEST user and grants necessary privileges (CONNECT, RESOURCE, CREATE TABLE, UNLIMITED TABLESPACE).
4. Auto-Cleanup: The container is stopped after the session unless --keep-db is passed.

Sources: tests/conftest.py:53-120, tests/README.md:31-36

Database Fixtures

Fixtures in conftest.py simplify database interactions:

• oracle_engine: A session-scoped FlextDbOracleApi instance for direct database verification.
• oracle_loader: A function-scoped FlextTargetOracleLoader instance for testing target-specific loading logic.
• clean_database: An autouse-style fixture that drops all tables in the user_tables catalog before each test to ensure isolation.

Sources: tests/conftest.py:123-167, tests/README.md:65-71

Unit Testing and Mocking

Unit tests target the FlextTargetOracle client and FlextTargetOracleLoader without requiring an active database. They rely heavily on unittest.mock to simulate the FlextDbOracleApi.

Example Mock Configuration

The mock_oracle_api fixture provides a MagicMock that returns successful r result objects for common operations like connect, execute_query, and get_tables.

@pytest.fixture
def mock_oracle_api() -> Mock:
    mock_api = Mock()
    mock_api.__enter__ = Mock(return_value=mock_api)
    for method, value in _MOCK_API_OK_RETURNS.items():
        getattr(mock_api, method).return_value = MagicMock(
            success=True, failure=False, value=value
        )
    return mock_api

Sources: tests/conftest.py:192-205, tests/unit/test_target.py:22-60

Integration and Performance Testing

Integration tests verify the translation of Singer messages into Oracle-specific SQL.

Test Scenarios

• Simple Table Creation: Verifies that ensure_table_exists creates tables in the USER_TABLES catalog with correct types (e.g., VARCHAR2, NUMBER).
• JSON Storage Mode: Tests the capability to store nested Singer records in Oracle CLOB or JSON columns.
• Bulk Load Performance: Benchmarks LOAD_METHOD_BULK_INSERT by loading large record sets (e.g., 5,000 records) and measuring elapsed time.
• Merge Mode: Validates Upsert/Merge logic by verifying that subsequent records with the same primary key update existing rows.

Sources: tests/integration/test_oracle.py:61-125, tests/performance/test_performance.py:23-55

Module Governance

The TestsFlextTargetOracleModuleGovernance class enforces architectural standards using importlib and inspect. It ensures:

• Logger Standards: Package modules must not define module-level loggers (usage of u.fetch_logger is expected).
• Function Boundaries: Top-level functions are forbidden outside of explicitly approved entry points to maintain clean module interfaces.
• Model Isolation: The TargetOracle namespace must not wrap Meltano or core Singer models, maintaining a strict separation between the target implementation and the Singer protocol definitions.

Sources: tests/unit/test_module_governance.py:70-117

Quality Gates and Standards

The project enforces several quality gates via pyproject.toml and automated check scripts:

• Coverage: Minimum test coverage requirement is set to 80% (though pyproject.toml defines a lower fail_under = 20 for development, the standard is higher).
• Typing: All code must pass mypy and pyrefly checks.
• Style: Code must be formatted with Black and linted with Ruff.
• Banned APIs: pyproject.toml bans standard libraries like argparse in favor of flext_cli to ensure ecosystem consistency.

Sources: pyproject.toml:137-142, CONTRIBUTING.md:95-105, tests/README.md:78-80

The testing strategy provides a robust framework that balances execution speed via unit testing with deep verification through automated Oracle container orchestration for integration and performance benchmarks.