Testing Strategy Overview

Relevant source files

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

• tests/__init__.py
• tests/base.py
• tests/utilities.py
• tests/protocols.py
• tests/models.py
• tests/constants.py
• tests/unit/fixtures.py
• pyproject.toml

The testing strategy for the flext-tap-oracle project is built upon a layered architecture that leverages the FLEXT framework's core testing capabilities while providing domain-specific specializations for Oracle database and Singer protocol interactions. The strategy prioritizes composition over inheritance and utilizes automated container orchestration for high-fidelity integration testing.

This framework ensures Singer protocol compliance, robust database connection handling, and accurate data extraction performance. It incorporates unit testing, end-to-end (E2E) integration, and performance benchmarking to maintain a zero-debt baseline as defined in the project quality gates.
Sources: README.md:55-58, tests/utilities.py:15-25, pyproject.toml:430-445

Testing Architecture

The project employs a specialized testing facade that combines generic FLEXT test utilities with Oracle-specific implementations. This is achieved through a composition-based pattern in files like tests/utilities.py, tests/models.py, and tests/protocols.py, where specialized classes inherit from both the core flext_tests library and the local flext_tap_oracle production code.

Test Component Hierarchy

The following diagram illustrates the relationship between the test facade and the underlying core and production components.

The hierarchy ensures that tests have access to generic FLEXT assertions (via the Tests namespace) and domain-specific Oracle helpers (via the TapOracle namespace).
Sources: tests/utilities.py:15-30, tests/protocols.py:15-30, tests/models.py:15-30

Integration and Docker Strategy

A core pillar of the testing strategy is the use of managed Oracle containers for integration and E2E testing. The project utilizes flext_tests.tk (Toolkit) to manage the lifecycle of a shared Oracle container, ensuring consistent environments for database-dependent tests.

Container Lifecycle Flow

The test suite automatically handles container availability and environment setup before executing database-reliant tests.

The docker_control fixture manages the flext-oracle-db-test container, while skip_e2e_if_no_oracle prevents test failures when the environment is not configured for database access.
Sources: tests/unit/fixtures.py:27-56, tests/unit/fixtures.py:108-140, tests/constants.py:25-35

Shared Test Constants

Test environments are strictly controlled via environment variables defined in the Tests namespace of the constants module.

Constant Name	Value / Purpose
SHARED_CONTAINER_NAME	flext-oracle-db-test
SHARED_CONTAINER_USER	flext_test
ORACLE_PORT_ENV	ORACLE_PORT (Mapping to host-resolved port)
TEST_MODE_ENV	ORACLE_TAP_TEST_MODE
SOCKET_TIMEOUT_SECONDS	0.5 (Used for DB availability checks)

Sources: tests/constants.py:25-55

Test Data and Mocking

Testing data flow involves the generation of mock Oracle records and the validation of Singer stream configurations. The TestsFlextTapOracleUtilities.TapOracle class provides static methods to streamline this process.

• Mock Data Generation: generate_mock_oracle_data creates sequences of JSON mappings representing database rows.
• Config Creation: create_test_oracle_config facilitates the creation of valid Pydantic-based settings for the tap.
• Singer Validation: validate_oracle_connection_config ensures that mandatory fields like host, port, and service_name are present and non-empty.

Sources: tests/utilities.py:40-90

Mocking Protocols

The system defines runtime_checkable protocols to facilitate mocking of database interactions:

• MockOracleConnection: Defines connect, disconnect, and execute_query methods.
• TestDataProvider: Abstracts the retrieval of test tables and data.
• TestAssertion: Standardizes Oracle-specific assertions, such as assert_extraction_results_match.

Sources: tests/protocols.py:38-115

Quality Gates and Categorization

The pyproject.toml configuration defines strict markers and coverage thresholds to maintain code quality.

Marker	Description
unit	Isolated unit tests for logic and models.
integration	Tests requiring communication between modules.
e2e	End-to-end tests requiring a live Oracle instance.
docker	Tests specifically requiring a Docker environment.
resilience	Tests evaluating circuit breakers and retry logic.

The project enforces a fail_under = 20 coverage threshold as a baseline integration gate, with standard make verbs (check, test, val) providing the execution interface.
Sources: pyproject.toml:440-455, pyproject.toml:95-100, README.md:55-60

Summary

The flext-tap-oracle testing strategy leverages a sophisticated facade pattern and automated container orchestration to ensure the reliability of the Singer tap. By combining strict protocol definitions with flexible mock data generation and live database integration, the strategy provides high confidence in the tap's performance and compliance with both Oracle and Singer standards.
Sources: tests/base.py:1-20, tests/unit/fixtures.py:80-95