Testing Strategy (Pytest)
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for the mt5-docker project is built around a multi-layered approach using the Pytest framework to ensure the stability and accuracy of a Dockerized MetaTrader 5 environment. It encompasses 67 comprehensive tests divided into three primary categories: static analysis, runtime validation, and bridge service verification. This strategy ensures that configuration files are consistent, containerized services start correctly, and the gRPC bridge accurately mirrors the official MetaTrader 5 Python API.
The suite utilizes Poetry for dependency management and is designed to be environment-aware, with specific logic to handle isolated test containers that do not conflict with production instances. The framework supports both synchronous and asynchronous validation, leveraging specialized fixtures for container lifecycle management and gRPC communication.
Sources: README.md:20-22, tests/test_static.py:1-12, tests/conftest.py:1-14
Test Categorization and Hierarchy
The test suite is logically organized into three distinct tiers, each serving a specific role in the development and deployment lifecycle.
1. Static Validation (test_static.py)
These tests validate configuration files, shell scripts, and build artifacts without requiring a running Docker container. They focus on the "Single Source of Truth" (SSOT) for versions, shell script syntax, and Dockerfile structure.
- Version Consistency: Ensures versions in
versions.envmatchDockerfileARGs andcompose.yamlbuild arguments. - Script Integrity: Validates Bash syntax and executable permissions for all startup and maintenance scripts.
- Structure Validation: Checks OCI labels, volume declarations, and port exposures in the Docker configuration.
Sources: tests/test_static.py:15-20, tests/test_static.py:101-130, tests/constants.py:108-115
2. Runtime Validation (test_runtime.py)
These tests require a running Docker container (typically named mt5docker-test). They verify the internal environment of the container, including service health and Python package availability.
- Container Health: Checks if the container is running, healthy, and not in a restart loop.
- Environment Verification: Validates the dual-Python architecture (Linux Python 3.13 and Wine Python 3.12).
- Service Supervision: Verifies that s6-overlay services (like
svc-mt5server) are properly initialized and supervised.
Sources: tests/test_runtime.py:1-15, tests/test_runtime.py:64-90, tests/test_runtime.py:270-285
3. Bridge Service Validation (test_bridge_validation.py)
This specialized layer focuses on the gRPC bridge that enables remote control of MetaTrader 5. It performs signature matching against the official MT5 API and tests service recovery scenarios.
Sources: tests/test_bridge_validation.py:1-10, tests/test_bridge_validation.py:252-270
Testing Infrastructure and Lifecycle
The project uses a session-scoped fixture strategy to manage the lifecycle of an isolated test container. This avoids interference with production environments by using dedicated ports and container names.
Container Lifecycle Flow
The following diagram illustrates the automated process of preparing the test environment when runtime or bridge tests are executed.
The framework prioritizes speed by attempting a 2-second fast-path gRPC check on existing containers before resorting to progressive backoff or full container initialization.
Sources: tests/conftest.py:165-245, tests/conftest.py:255-275
Configuration and Constants
Test configuration is centralized in tests/constants.py, utilizing Python namespaces and Enums to maintain a technical and organized structure.
Key Test Configuration Options
| Variable | Source | Description |
|---|---|---|
MT5DOCKER_TEST_GRPC_PORT | Env / 48812 | Dedicated gRPC port for isolated test container. |
MT5DOCKER_TEST_VNC_PORT | Env / 43000 | Dedicated VNC port for isolated test container. |
MT5DOCKER_TEST_STARTUP_TIMEOUT | Env / 420s | Maximum time allowed for MT5 and Wine initialization. |
MT5_AUTO_CREATE_DEMO | Env / 1 | Enables/disables zero-touch demo account creation. |
Sources: tests/constants.py:145-155, tests/conftest.py:59-78
Version Requirements
The test suite enforces specific versions to maintain compatibility between the Linux host and the Wine-based Windows environment.
| Component | Required Version | Context |
|---|---|---|
| System Python | 3.13 | mt5linux compatibility on Linux. |
| Wine Python | 3.12 | MetaTrader5 package and NumPy compatibility. |
| NumPy | 1.26.x | Required for Wine stability. |
| gRPCIO | >= 1.76.0 | Required for protobuf generated stubs. |
Sources: tests/test_static.py:59-95, tests/constants.py:230-245
Bridge API Validation Strategy
A critical component of the testing strategy is ensuring the gRPC bridge correctly implements the MetaTrader 5 API. The suite defines a typed contract of the official API and validates the bridge against it.
Function Signature Matching
The bridge is validated against a mapping of official functions, ensuring parameters and return types match the MQL5 Python documentation.
OFFICIAL_MT5_FUNCTIONS = {
"initialize": {
"params": ["path", "login", "password", "server", "timeout", "portable"],
"optional": ["path", "login", "password", "server", "timeout", "portable"],
"returns": "bool",
},
"copy_rates_from": {
"params": ["symbol", "timeframe", "date_from", "count"],
"optional": [],
"returns": "ndarray | None",
}
}
Sources: tests/test_bridge_validation.py:35-60, tests/test_bridge_validation.py:85-100
Service Recovery and Stability
The strategy includes failure simulation to ensure the bridge and its supervisor (s6-overlay) can recover from critical errors.
- Restart Tokens: The
health_monitor.shscript signalssvc-mt5servervia aRESTART_TOKENfile in/tmp/rather than performing direct process kills. - Idempotency Markers: The Wine prefix initialization uses a
.build-completemarker to ensure that interrupted builds are detected and restarted from scratch. - Protobuf Integrity: Tests verify that the Wine protobuf runtime version is greater than or equal to the gencode baked into the generated stubs (
mt5_pb2.py) to prevent import-time crashes.
Sources: tests/test_static.py:440-455, tests/test_static.py:270-285, tests/test_static.py:290-310
Execution and CI Integration
The project uses Poetry to manage test execution and environment variables via .env files.
# Run all tests through Poetry
poetry run pytest tests/ -v
# Run with coverage report
poetry run pytest tests/ --cov=src --cov-report=html
The test suite is designed for "Continuous Green" operation, meaning no task is considered complete while the environment is broken or coverage is missing. Automated gates include Ruff for linting, Pyright for type checking, and Pytest for functional validation.
Sources: README.md:215-225, pyproject.toml:75-90, AGENTS.md:38-42
The comprehensive Pytest strategy ensures that every layer of the mt5-docker environment—from the low-level Wine prefix configuration to the high-level gRPC trading API—is validated for accuracy, stability, and performance.