Integration Testing
Relevant source files
The following files were used as context for generating this wiki page:
Integration testing within the FLEXT Observability project focuses on validating the interactions between multiple internal components and ensuring seamless integration with external systems, such as the flext-core library and database layers. These tests are designed to execute quickly—typically in under 10 seconds—while using real implementations in controlled environments to validate data flow and component coordination.
Sources: tests/integration/README.md:16-22, tests/README.md:17-18
The testing strategy follows a layered approach, moving from isolated unit tests to complex, multi-component integration scenarios. This ensures that the observability platform functions correctly when embedded in larger business workflows, such as HTTP request handling or database transaction monitoring.
Sources: tests/integration/test_phase_11_integration.py:1-9, src/flext_observability/README.md:10-18
Architecture and Test Components
Integration testing leverages several core observability services and platform-level orchestrators to simulate real-world usage. Key components involved in these tests include the FlextObservabilityMasterFactory, various specialized services (Metrics, Tracing, Alerting), and context management systems that handle correlation and trace IDs across service boundaries.
Sources: tests/integration/README.md:44-63, tests/integration/test_phase_11_integration.py:270-282
Integration Components
| Component | Description |
|---|---|
FlextObservabilityMasterFactory | Central factory for creating validated observability entities (metrics, traces, alerts). |
FlextObservabilityContext | Manages correlation IDs and trace IDs across component boundaries. |
FlextObservabilitySampling | Determines sampling rates and decisions for high-volume operations. |
FlextObservabilityPerformance | Monitors the overhead and performance of observability operations. |
FlextObservabilityAdvancedContext | Handles metadata and baggage propagation for complex distributed flows. |
Sources: tests/integration/test_phase_11_integration.py:27-35, tests/integration/test_phase_11_integration.py:126-146, src/flext_observability/README.md:46-55
Component Interaction Flow
The following diagram illustrates the typical data flow during an integration test, where a factory creates an entity that is then processed by a service layer within a shared container.
Realistic Scenario Testing
Integration tests in Phase 11 combine HTTP operations, database interactions, and error handling to mirror production environments. These tests validate that observability data is correctly correlated even when spanning different technical domains.
Sources: tests/integration/test_phase_11_integration.py:1-9
HTTP and Database Integration
Tests simulate a POST request to an API endpoint, recording the total request count, duration in milliseconds, and eventual success. Simultaneously, database integration tests validate that queries (e.g., SELECT) result in metrics for query totals, execution time histograms, and rows-returned gauges.
Sources: tests/integration/test_phase_11_integration.py:27-72
Distributed Tracing Correlation
Integration testing verifies that a single correlation_id can be propagated across an entire workflow, linking API requests, business logic operations, and database queries.
Context and Sampling Management
Integration tests validate the advanced context management system, including metadata snapshots and baggage propagation. This is critical for ensuring that observability data persists across asynchronous boundaries.
Advanced Context Workflow
- Metadata Update: Context is updated with
user_id,request_id, andtenant_id. - Snapshot Creation: A snapshot is taken, capturing current IDs, metadata, and baggage.
- Context Restoration: The context is cleared and subsequently restored from the snapshot to ensure data integrity.
Sources: tests/integration/test_phase_11_integration.py:126-150
Sampling Logic
The FlextObservabilitySampling component is tested for its ability to make sampling decisions based on environment (e.g., "production") and operation rates. Tests ensure that a should_sample decision is always reached before metrics or traces are exported.
Sources: tests/integration/test_phase_11_integration.py:30-36, tests/integration/test_phase_11_integration.py:152-168
Error Handling and Escalation
Integration tests validate the FlextObservabilityErrorHandling component, focusing on the ability to record errors and determine when they should trigger alerts based on defined thresholds.
Error Configuration Table
| Configuration | Usage in Testing | Purpose |
|---|---|---|
escalation_threshold | Set to 3 | Number of errors before severity is escalated. |
alert_cooldown | Set to 30 | Seconds to wait between duplicate alerts. |
error_type | DatabaseConnectionError | Specific domain error being tested. |
severity | WARNING / ERROR | Initial and escalated severity levels. |
Sources: tests/integration/test_phase_11_integration.py:76-92
Execution and Quality Standards
Integration tests are executed using standard pytest commands, often utilizing specific markers to separate them from faster unit tests or slower end-to-end (E2E) tests.
- Standard Execution:
pytest tests/integration/ -v - Coverage Reporting:
pytest tests/integration/ --cov=src/flext_observability - Performance Markers:
pytest tests/ -m integration
Sources: tests/integration/README.md:73-82, tests/README.md:120-134
These tests are a requirement for passing quality gates, which mandate at least 95% coverage across the module and 100% coverage for core observability functions.
Sources: tests/README.md:139-142, README.md:38-40
Summary
Integration testing provides the necessary assurance that the FLEXT Observability components—from the low-level FlextContainer to high-level platform orchestrators—work in concert. By simulating production-like scenarios involving HTTP, databases, and error escalation, the project ensures reliable telemetry collection and correlation across the entire FLEXT ecosystem.
Sources: tests/integration/README.md:16-22, tests/e2e/README.md:14-22