Test Utility Functions

Relevant source files

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

• tests/utilities.py
• tests/models.py
• tests/protocols.py
• tests/typings.py
• tests/constants.py

The test utility functions within the flext-tap-oracle project provide a structured framework for validating Oracle Singer tap functionality. These utilities are built using a composition-based architecture that integrates generic testing capabilities from flext_tests with domain-specific logic for Oracle database interactions and Singer protocol compliance.

The scope of these utilities includes mock data generation, configuration validation, protocol enforcement, and shared test constants. By centralizing these functions, the project ensures a consistent "zero-debt baseline" for integration, unit, and end-to-end testing of the Oracle extraction pipeline.

Sources: tests/utilities.py:1-15, tests/models.py:1-15, README.md:12-15

Architecture and Composition

The testing infrastructure follows a strict composition pattern rather than traditional inheritance. The primary facade classes, such as TestsFlextTapOracleUtilities, combine methods from the core flext_tests library and the production FlextTapOracleUtilities to create a unified interface for test authors.

The diagram above illustrates how the test utility facade aggregates core testing capabilities and domain-specific Oracle helpers.

Sources: tests/utilities.py:17-31, tests/models.py:17-31

Domain-Specific Test Helpers

The TapOracle namespace within the utility classes contains methods specifically designed for Oracle tap testing, covering connection setup, stream configuration, and data mocking.

Configuration Helpers

These functions allow for the rapid creation of valid configuration objects required for initializing the tap or testing its connection logic.

Function	Purpose	Key Parameters
create_test_oracle_config	Generates a JSON mapping for Oracle connection settings.	host, port, service_name, username, password
create_test_singer_stream	Creates a configuration for a Singer stream.	stream_name, table_name, replication_method
validate_oracle_connection_config	Validates that all required connection fields are present and non-empty.	settings (JSON Mapping)

Sources: tests/utilities.py:33-72

Mock Data Generation

The generate_mock_oracle_data function facilitates the creation of deterministic datasets for testing extraction logic without requiring a live Oracle instance.

@staticmethod
def generate_mock_oracle_data(
    table_name: str,
    row_count: int = 10,
    **kwargs: t.JsonValue,
) -> t.SequenceOf[t.JsonMapping]:
    """Generate mock Oracle data for testing."""
    data: list[t.JsonMapping] = []
    for i in range(row_count):
        row: dict[str, t.JsonValue] = {
            "id": i + 1,
            "name": f"Test Record {i + 1}",
            "table_name": table_name,
        }
        row.update(kwargs)
        data.append(row)
    return data

Sources: tests/utilities.py:74-91

Test Models and Protocols

To ensure type safety and protocol compliance during testing, the system defines specific models and runtime-checkable protocols.

Test Entity Models

Models defined in tests/models.py utilize Pydantic (via flext-core) to enforce schemas on test-specific data structures like mock connections and extraction configurations.

• TestOracleConnection: Validates host, port, and credentials while providing a connection_string property for verification.
• TestSingerStream: Models the metadata for a source table, including replication methods (e.g., FULL_TABLE).
• TestExtractionConfig: Defines parameters for performance testing, such as batch_size and parallel_streams.

Sources: tests/models.py:33-95

Testing Protocols

Protocols define the expected behavior of mock objects, such as a mock Oracle connection or a data provider, allowing for flexible dependency injection during tests.

Shared Test Constants

The project maintains a centralized repository of constants in tests/constants.py to ensure consistency across different test types (unit vs. integration).

• Shared Container Info: Defines defaults for Docker-based testing, such as SHARED_CONTAINER_NAME ("flext-oracle-db-test") and SHARED_CONTAINER_DEFAULT_PORT (1522).
• Environment Variables: Maps keys like FLEXT_TAP_ORACLE_ORACLE_HOST to standard environment variable strings used by the tap's settings manager.
• Mock Defaults: Provides standard unit test values for credentials and batch sizes (e.g., UNIT_BATCH_SIZE = 1000).

Sources: tests/constants.py:16-65

Conclusion

The "Test Utility Functions" serve as the backbone for the quality assurance process in the flext-tap-oracle repository. By utilizing a composition-based architecture and strictly defined protocols and models, the utilities provide a robust environment for simulating Oracle database behaviors and validating the Singer tap's extraction logic. This structure allows developers to maintain high test coverage while ensuring that the tap remains compliant with both Oracle-specific constraints and Singer protocol standards.