Protocol Parity Tests
Relevant source files
The following files were used as context for generating this wiki page:
Protocol Parity Tests are a critical component of the mcpi-recompiled project, designed to ensure the reconstructed game engine maintains 1:1 compatibility with the original Minecraft: Pi Edition 0.1.1 alpha programming API. These tests validate the implementation of the TCP-based protocol, which traditionally operates on port 4711.
The testing suite is divided into two primary focuses: unit testing the string-based command parser and integration testing the asynchronous TCP server. By utilizing a protocol-compatible API test harness, the project tracks parity between the new C++ implementation and the original game behavior.
Sources: README.md:9-25, tests/protocol_tests.cpp:21-50
Testing Architecture
The testing infrastructure is integrated into the CMake build system and leverages a custom expect utility to validate conditions. Tests are categorized into protocol (parser logic) and api_server (network communication).
Component Overview
| Component | Description | Source File |
|---|---|---|
| Protocol Parser | Logic for decomposing string inputs into Command structures. | src/api/Command.cpp |
| API Server | Multi-threaded TCP server handling socket lifecycle and request dispatching. | src/api/ApiServer.cpp |
| Command Structure | Data model representing a validated API request (Name + Arguments). | src/api/Command.hpp |
| Test Harness | Executables that simulate client connections and verify server responses. | tests/api_server_tests.cpp |
Sources: CMakeLists.txt:47-64, src/api/Command.hpp:12-15
Command Parser Validation
The parser tests ensure that the mcpi::api::parse_command function correctly handles the specialized syntax of the MCPI protocol. This includes validating command names, argument counts, and string payloads.
The following flowchart illustrates the parsing logic validated by the tests:
The parser handles various command formats including those with multiple numeric arguments, zero arguments, and complex string payloads.
Sources: src/api/Command.cpp:24-60, tests/protocol_tests.cpp:21-45
Verified Command Patterns
- Parameterized:
world.setBlock(1,2,3,57)-> 4 arguments. - Zero-argument:
player.getPos()-> 0 arguments. - String Payload:
chat.post(Hello from Pi)-> 1 argument preserving spaces. - Failure Cases: Empty input, missing parentheses, or trailing data after the closing parenthesis.
Sources: tests/protocol_tests.cpp:24-48
API Server Integration
The integration tests verify the end-to-end lifecycle of a protocol request, from socket connection to response delivery. The test suite spins up a local ApiServer instance on an ephemeral port to avoid conflicts.
The following sequence diagram shows the communication flow during an integration test:
The server implementation uses SO_RCVTIMEO to prevent blocking indefinitely during reads, allowing the server to check the is_running atomic flag regularly.
Sources: src/api/ApiServer.cpp:78-100, tests/api_server_tests.cpp:94-110
Network Configuration
Integration tests check for proper cross-platform socket handling, ensuring compatibility between Linux and Windows (Winsock2).
| Feature | Implementation Detail | Sources |
|---|---|---|
| Port Selection | Port 0 is used in tests to trigger OS-level ephemeral port binding. | tests/api_server_tests.cpp:94 |
| Timeout | Receive timeout is set to 200ms for responsiveness. | src/api/ApiServer.cpp:44-54 |
| Concurrency | A worker thread handles the accept loop and client processing. | src/api/ApiServer.cpp:208-210 |
| Line Buffering | Commands are processed only when a \n character is encountered. | src/api/ApiServer.cpp:138-142 |
Summary
Protocol Parity Tests are the primary mechanism for validating that mcpi-recompiled remains a faithful reconstruction. By strictly testing the Command parsing logic and the ApiServer network implementation, the project ensures that external scripts and tools designed for the original Minecraft: Pi Edition continue to function without modification.
Sources: README.md:14-20, src/main.cpp:11-15