Testing Strategy Overview

Relevant source files

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

• AGENTS.md
• DOCKER_COMPOSE_USAGE.md
• tests/integration/test_parametrized.py
• tests/unit/test_model_schema_validation.py
• tests/unit/test_wal.py
• tests/unit/test_utilities_unit.py
• tests/integration/test_bridge_behavior.py
• tests/integration/test_edge_cases.py
• tests/constants.py
• tests/integration/test_client.py
• tests/integration/test_types_consistency.py
• tests/integration/test_real_mt5_validation.py

The testing strategy for the mt5linux project is designed to ensure the reliability and accuracy of the gRPC bridge between Linux environments and the MetaTrader 5 (MT5) Windows terminal. It employs a multi-layered approach encompassing unit testing for core utilities, integration testing with live MT5 instances, property-based testing for edge-case discovery, and protocol compliance validation against the official MetaTrader 5 PyPI package.

The framework emphasizes "Continuous Green" execution, requiring comprehensive coverage across Python versions and using tools such as Ruff, Pyright, Mypy, and Pytest. Tests are treated as executable checks of canonical policy, ensuring that the software reflects the intended behavior of the MT5 API while maintaining stability through resilience features like circuit breakers and Write-Ahead Logs (WAL).
Sources: AGENTS.md:38-40, AGENTS.md:58-63

Test Infrastructure and Environment

The project utilizes Docker Compose as the primary mechanism for managing isolated MT5 test environments. This allows for parallel execution of test scenarios with distinct configurations, such as different container names, ports, and MT5 credentials.

Docker-Based Isolation

Test isolation is achieved by parametrizing container and network configurations. Each test run can specify unique ports for gRPC, VNC, and Health checks, as well as distinct volume names for persistent settings.

The diagram above illustrates how the test runner spawns isolated MT5 environments using environment variables to prevent port and volume conflicts.
Sources: DOCKER_COMPOSE_USAGE.md:1-12, DOCKER_COMPOSE_USAGE.md:88-105

Configuration Parameters

Variable	Default	Purpose
MT5_GRPC_PORT	28812	gRPC server communication port
MT5_HEALTH_PORT	28002	Endpoint for terminal health checks
MT5_CONTAINER_NAME	mt5linux-test	Prefix for container and volume identification
MT5_LOGIN	0	MT5 account login ID

Sources: DOCKER_COMPOSE_USAGE.md:16-35, tests/constants.py:84-88

Testing Layers

Unit Testing

Unit tests focus on individual components without requiring an active MT5 terminal or gRPC server. Key areas include Pydantic model validation, Write-Ahead Log (WAL) transitions, and utility transformations.

• Model Validation: Ensures that MT5Models have the correct fields, types, and immutability (frozen models).
• WAL Testing: Validates the status transitions (e.g., PENDING -> SENT -> VERIFIED) and recovery logic using a temporary SQLite database.
• Utility Logic: Tests internal logic such as the TransactionOrchestrator using AsyncMock to simulate gRPC calls and health checks.

Sources: tests/unit/test_model_schema_validation.py:1-12, tests/unit/test_wal.py:1-10, tests/unit/test_utilities_unit.py:1-15

Integration Testing

Integration tests validate the end-to-end communication between the mt5linux client and a real MT5 terminal running inside a container.

Integration tests cover account information, symbol selection, OHLCV rate copying, and order execution.
Sources: tests/integration/test_bridge_behavior.py:1-15, tests/integration/test_client.py:1-15

Parametrized and Property-Based Testing

The project uses pytest.mark.parametrize for broad symbol/timeframe coverage and Hypothesis for property-based testing.

• Symbol Matrix: Tests are executed across Major Pairs, Cross Pairs, Metals, and Indices.
• Property Validation: Hypothesis generates random inputs (e.g., volume, deviation) to ensure properties hold true, such as "returned rates count should be <= requested count."

Sources: tests/integration/test_parametrized.py:1-15, tests/integration/test_parametrized.py:270-285

Protocol and Model Compliance

A critical part of the testing strategy is ensuring that the mt5linux implementation remains compatible with the official MetaTrader5 PyPI package.

Compliance Checks

1. Method Parity: Validates that MT5Protocol implements all public methods found in the official API (e.g., symbols_get, order_send, copy_rates_from).
2. Field Consistency: Compares MT5Models fields and field order against the namedtuples returned by the real MT5 module.
3. Type Consistency: Uses get_type_hints to verify that TypedDicts used in the protocol match the Pydantic models.

Sources: tests/integration/test_real_mt5_validation.py:1-15, tests/integration/test_types_consistency.py:1-12

Error Handling and Resilience Testing

Tests specifically target the system's ability to handle transient and permanent failures.

• Resilience Features: Validates the CircuitBreaker states (CLOSED, OPEN, HALF_OPEN) and the TransactionOrchestrator retry logic.
• Edge Cases: Tests invalid inputs like non-existent symbols, reversed date ranges, and negative bar counts.
• Health Checks: Verifies that the client correctly identifies terminal availability and recovers from disconnected states.

Sources: tests/unit/test_utilities_unit.py:590-630, tests/integration/test_edge_cases.py:1-15, tests/integration/test_client.py:320-350

Conclusion

The mt5linux testing strategy provides a robust validation framework that combines traditional testing tiers with advanced protocol introspection and property-based verification. By leveraging Docker for environment management and enforcing strict model compliance, the project ensures high reliability for algorithmic trading operations on Linux systems. Significant emphasis is placed on ensuring the system fails gracefully and recovers automatically from network or terminal instabilities.
Sources: AGENTS.md:58-63, tests/constants.py:465-485