Test Type Annotations

Relevant source files

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

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

Test Type Annotations in the flext-tap-oracle project provide a structured, type-safe framework for validating Oracle-specific tap functionality. This system uses a composition-based architecture to combine generic test types from flext_tests with domain-specific annotations for Oracle database connections, Singer streams, and extraction performance metrics.

The primary purpose of these annotations is to ensure consistency across test suites, mock data generation, and assertion logic. By utilizing Pydantic-based models and runtime-checkable protocols, the testing framework can validate complex data structures like Oracle record sets and Singer stream configurations before execution.

Sources: tests/typings.py:1-15, tests/protocols.py:1-15

Type Composition Architecture

The test suite avoids traditional inheritance in favor of composition to manage its type system. The TestsFlextTapOracleTypes class aggregates types from FlextTestsTypes (generic testing), FlextTypes (core framework), and FlextTapOracleTypes (production domain).

The diagram above illustrates how test-specific types are namespaced within TapOracleTest while inheriting the broader type context of the FLEXT ecosystem.

Sources: tests/typings.py:18-35

Domain-Specific Test Types

The project defines several specialized types for Oracle-specific testing scenarios:

Type Name	Definition	Description
TestOraclePort	Literal[1521, 10521, 1522]	Supported ports for Oracle test containers.
MockOracleRecord	t.MappingKV[str, FlextTypes.Scalar]	A single row of mock Oracle data.
MockOracleTable	t.SequenceOf[MockOracleRecord]	A collection of mock records representing a table.
TestPerformanceResult	t.MappingKV[str, float | int | str]	Metrics for extraction speed and volume.

Sources: tests/typings.py:44-51

Test Protocols and Interfaces

The testing framework utilizes runtime_checkable protocols to define interfaces for mock components and assertions. These protocols allow tests to verify that mock objects (like database connections) adhere to the required contract without requiring strict inheritance.

Mock Connection and Data Providers

The TapOracle.Tests namespace contains protocols for simulating Oracle interactions:

• MockOracleConnection: Defines connect(), disconnect(), and execute_query() methods for simulating DB drivers.
• TestDataProvider: Standardizes how test tables, data, and configurations are retrieved for unit tests.

The sequence above shows the typical interaction between a test case and the defined protocols for data retrieval and mock execution.

Sources: tests/protocols.py:35-70

Test Assertions

The TestAssertion protocol defines a standardized set of validation methods used across the test suite:

• assert_oracle_connection_successful: Validates connection settings.
• assert_singer_stream_valid: Verifies stream metadata against Singer standards.
• assert_extraction_results_match: Performs deep comparison between expected mock data and actual tap output.

Sources: tests/protocols.py:75-103

Test Models and Data Structures

Test models are implemented using Pydantic-based Entity classes within tests/models.py. These models provide runtime validation for test configurations and database state.

Core Test Models

Model Class	Key Fields	Purpose
TestOracleConnection	host, port, service_name, username	Validates credentials and generates connection strings.
TestSingerStream	stream_name, table_name, replication_method	Models a Singer stream for catalog validation.
TestOracleTable	table_name, schema_name, column_count	Models Oracle schema metadata for discovery tests.
TestExtractionConfig	batch_size, parallel_streams, timeout	Configures and validates extraction performance parameters.

Sources: tests/models.py:38-115

Data Flow for Mock Generation

The TestsFlextTapOracleUtilities class uses these models and types to generate consistent mock data.

This flowchart illustrates the progression from configuration and data generation using types/models to final validation via assertion protocols.

Sources: tests/utilities.py:36-95

Test Constants

Test annotations are supported by a comprehensive set of constants that define environment variables and default values for the testing environment.

• Container Settings: SHARED_CONTAINER_NAME, SHARED_CONTAINER_PORT_PREFIX, and SHARED_CONTAINER_SERVICE_NAME define the standard Oracle test environment.
• Environment Variables: Constants like SHARED_ORACLE_HOST_ENV and ORACLE_PASSWORD_ENV map system environment variables to the test configuration.
• Unit Defaults: UNIT_ORACLE_USER, UNIT_ORACLE_PASSWORD, and UNIT_BATCH_SIZE provide fallback values for isolated unit tests.

Sources: tests/constants.py:20-75

Conclusion

The "Test Type Annotations" system in flext-tap-oracle provides a robust, type-safe foundation for testing Oracle database integrations. By combining composition-based type definitions, runtime-checkable protocols, and Pydantic-validated models, the project ensures that test components remain consistent with the production domain while offering the flexibility required for complex mocking and performance benchmarking.