Unit & Integration Testing
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT Meltano project implements a comprehensive, enterprise-grade testing infrastructure designed to ensure the reliability of the Go ↔ Python bridge library. The suite is categorized into distinct layers, ranging from isolated unit tests to complex integration scenarios involving external dependencies like PostgreSQL, Redis, and the Meltano CLI. The testing strategy enforces high quality gates, targeting 90%+ coverage across all core modules and requiring zero flaky tests in CI/CD environments.
Sources: tests/README.md:12-24, tests/README.md:197-206
Testing Architecture and Hierarchy
The testing framework is structured into five primary categories, each serving a specific role in the validation lifecycle. This hierarchy ensures that both individual logic components and system-wide interactions are verified.
Test Categories
| Category | Location | Purpose | Dependencies | Target Coverage |
|---|---|---|---|---|
| Unit Tests | unit/ | Isolated testing of individual components | None (Mocked) | 95%+ |
| Integration Tests | integration/ | Testing component interactions and external services | PostgreSQL, Redis, File System | 90% |
| End-to-End Tests | e2e/ | Complete workflow validation from API to output | Full Infrastructure | N/A |
| Extension Tests | extensions/ | Validation of specialized add-ons (e.g., Oracle OIC) | Extension-specific services | N/A |
| Fixtures | fixtures/ | Reusable test data and configuration | N/A | N/A |
Sources: tests/README.md:31-64, tests/README.md:197-200
Test Execution Flow
The project utilizes pytest as the primary execution engine, integrated with a Makefile for standardized quality gates.
The diagram shows the sequential promotion of code through the testing tiers before reaching CI/CD validation.
Sources: tests/README.md:70-85, pyproject.toml:440-465
Unit Testing Logic
Unit tests focus on the internal logic of the Python library without external side effects. Key areas include model validation, API contracts, and business rule enforcement.
Model and Schema Validation
The system uses Pydantic models for configuration, which are strictly validated during unit tests. For instance, m.Meltano.TapConfig and m.Meltano.TargetConfig are tested for required fields like tap_type and connection_config.
- Tap Validation: Ensures
tap_typeis non-empty andconnection_configis a valid dictionary. - Stream Info Validation: Validates stream schemas and status transitions (e.g., from
initialized).
Sources: tests/unit/test_models.py:15-50, tests/unit/test_models.py:90-115
Public API Contract
Tests for the public facade ensure that the singleton meltano instance remains stable and that its primary methods (tap, target, dbt) are callable.
def test_public_facade_contract(self) -> None:
"""The public singleton stays callable and stable."""
tm.that(type(meltano).fetch_global() is meltano, eq=True)
tm.that(callable(meltano.tap), eq=True)
tm.that(callable(meltano.target), eq=True)
Sources: tests/unit/test_api.py:18-24
Integration Testing
Integration tests verify the library's ability to communicate with real-world infrastructure. This is primarily handled via Docker-based services.
Docker-Based Service Validation
Integration tests utilize Docker containers for PostgreSQL and Redis to validate actual data operations. The TestsFlextMeltanoDockerIntegration class manages the lifecycle of these connections.
- PostgreSQL: Tests the canonical flow of
CREATE TABLE,INSERT,SELECT, andDROP. - Redis: Validates key-value operations (
set/get) and list operations (lpush/llen).
This diagram illustrates the lifecycle management of a Docker-based integration test.
Sources: tests/integration/test_docker_integration.py:20-80, tests/integration/test_docker_integration.py:145-165
Plugin and Project Integration
Integration testing also covers the file system and Meltano project structure. This includes verifying that create_project correctly persists the meltano.yml file and that plugin discovery requires an active project environment.
Sources: tests/unit/test_api.py:46-60, tests/unit/test_api.py:77-80
Testing Infrastructure and Fixtures
The project utilizes a centralized fixture management system to provide consistent test environments.
Fixture Organization
Fixtures are categorized into Data, Service, and Pipeline types to ensure reusability:
- Data Fixtures: Sample CSV/JSON datasets and Singer schema definitions.
- Service Fixtures: Mock service implementations and Docker-compose configurations.
- Pipeline Fixtures: Meltano project templates and Singer catalogs.
Sources: tests/fixtures/README.md:25-50, tests/fixtures/README.md:65-90
Quality Standards for Tests
Every test implementation must adhere to strict standards:
- Performance: Unit tests must execute in < 1 second; integration tests in < 30 seconds.
- Isolation: Tests must be independent and repeatable without state leakage.
- Documentation: Each test file requires module, class, and method docstrings explaining the Given/When/Then scenarios.
Sources: tests/README.md:143-180, tests/README.md:200-205
Summary
The Unit and Integration testing framework in flext-meltano provides a robust defense against regressions by combining fast, isolated logic checks with realistic infrastructure validation. By enforcing a 90% coverage threshold and leveraging Docker for service-level testing, the suite ensures that the Go ↔ Python bridge remains stable across diverse execution environments. Successful test execution is mandatory for all commits, integrated directly into the CI/CD pipeline through standardized quality gates.
Sources: tests/README.md:12-20, tests/README.md:230-245