Transport Characterization Tests
Relevant source files
The following files were used as context for generating this wiki page:
Transport Characterization Tests serve as a "locking" mechanism for the observable behavior of the FlextWebTransport and associated HTTP transport components. These tests are designed to pin down public and composed-helper behaviors prior to major architectural shifts, such as Method Resolution Order (MRO) decompositions or loc-cap refactoring. By establishing a green baseline, they ensure that the transport layer maintains its functional contract across internal implementation changes.
Sources: tests/unit/test_transports_characterization.py:1-10, tests/unit/README.md:1-10
Architecture and Scope
The characterization suite focuses on the FlextWebTransport class, ensuring it adheres to the TransportPlugin protocol and correctly handles lifecycle events like connection and disconnection. It validates the internal logic for timeout resolution, redirect following, and maximum redirect limits.
Component Relationships
The transport layer utilizes a mixin-based architecture to separate concerns, particularly the request pipeline and protocol implementation.
The diagram above illustrates how the main transport class inherits request handling capabilities and implements the required plugin protocols.
Sources: tests/unit/test_transports_characterization.py:15-61, src/flext_api/_protocols/_transports_request.py:18-25
Core Validation Logic
The tests focus on several key areas of the transport lifecycle and configuration:
Connection Lifecycle
The transport must validate URLs during the connect phase. Empty URLs are rejected with a failure result, while valid URLs return a success result containing the target URL. The disconnect method is verified to return a successful boolean status following a connection.
Client Configuration Defaults
Characterization tests enforce specific default values and override behaviors for the underlying HTTP client:
| Feature | Default Value | Override Behavior |
|---|---|---|
| Timeout | > 0 seconds | Accepts numeric override (e.g., 5.0) |
| Follow Redirects | True | Can be set to False via parameters |
| Max Redirects | 20 | Accepts integer override (e.g., 3) |
Sources: tests/unit/test_transports_characterization.py:23-53
Request Pipeline Characterization
The request pipeline, often implemented via FlextApiTransportsRequestMixin, is characterized by its ability to transform various input shapes into valid HttpRequest models.
The flow above describes how the transport shunts raw data into structured models before dispatching via the underlying HTTP client.
Payload Extraction
The transport supports multiple input formats for requests:
- Mappings (Dict): Merged with the connection URL.
- Raw Content (Str/Bytes): Assigned directly to the request body.
- Unsupported Types: Result in an immediate failure response.
Sources: src/flext_api/_protocols/_transports_request.py:44-67, tests/unit/test_smoke.py:65-75
Integration with Test Suite
As defined in the project's testing hierarchy, characterization tests are categorized as Unit Tests. They are designed to be fast (target <100ms per test) and isolated using mocks where necessary. They follow the AAA (Arrange, Act, Assert) pattern to ensure clear and maintainable test logic.
Execution Commands
Developers can run these specific characterization tests using standard pytest invocations or project-specific make verbs.
# Run characterization tests specifically
pytest tests/unit/test_transports_characterization.py -v
# Run as part of the fast unit test suite
make test-unit-fast
Sources: tests/README.md:10-50, tests/unit/README.md:30-45
Conclusion
Transport Characterization Tests are critical for maintaining the stability of the flext-api transport layer. By pinning the behavior of URL handling, client configuration, and request transformation, they provide the safety net required for refactoring core MRO structures without breaking the public API contract.