Testing Strategy & Harness

The testing strategy for the mcpi-recompiled project is a critical component of Phase 1, focusing on achieving parity with the original Minecraft: Pi Edition 0.1.1 alpha. Because the project aims for source reconstruction and native porting without distributing original assets, the test harness serves as the primary mechanism to validate that reconstructed game systems match documented observations and original behavior.

The harness is integrated directly into the CMake build system and employs a multi-tiered approach: unit testing for the command protocol parser and integration testing for the TCP API server. This ensures that the programming API, which operates on TCP port 4711, remains fully compatible with existing Minecraft Pi scripts.

Sources: README.md:12-25, CMakeLists.txt:47-65

Build System Integration

The project uses CMake to manage testing. Tests are optional and can be toggled using the MCPI_BUILD_TESTS flag. When enabled, the build system generates separate executables for different test suites and registers them with ctest.

Sources: CMakeLists.txt:9, CMakeLists.txt:47-50

Test Execution Flow

The following diagram illustrates the standard workflow for building and running the test suite.

Protocol Parser Testing

The protocol tests validate the mcpi::api::parse_command function. These tests ensure that raw string input from the TCP stream is correctly decomposed into a Command structure containing the function name and its associated arguments.

Parser Capabilities

The parser handles various command formats including:

• Standard multi-argument commands (e.g., world.setBlock(1,2,3,57)).
• Zero-argument commands (e.g., player.getPos()).
• Text payloads with spaces (e.g., chat.post(Hello from Pi)).

The parser also enforces strict validation, rejecting empty inputs, malformed strings, or commands with trailing data after the closing parenthesis.

Sources: tests/protocol_tests.cpp:21-50, src/api/Command.cpp:25-63

Command Data Structure

struct Command {
    std::string name;
    std::vector<std::string> arguments;
};

Sources: src/api/Command.hpp:12-15

API Server Integration Testing

Integration tests focus on the ApiServer class, simulating a real-world client-server interaction over the loopback interface. This validates the entire network stack, from socket binding and connection acceptance to request handling and response transmission.

Interaction Sequence

The test suite initializes a server on a random available port (port 0), connects a test socket, and verifies the round-trip of a command.

Network Configuration

The test harness configures several socket-level parameters to ensure reliable testing across platforms (Linux and Windows):

• SO_REUSEADDR: Allows the server to bind to a port immediately after a previous run.
• SO_RCVTIMEO: Sets a 200ms receive timeout to prevent tests from hanging on socket reads.
• Loopback Binding: Connections are restricted to INADDR_LOOPBACK for security and isolation.

Sources: src/api/ApiServer.cpp:45-56, src/api/ApiServer.cpp:189-195, tests/api_server_tests.cpp:49-55

Test Components Summary

The project maintains a clean separation between core logic and the testing harness, as defined in CMakeLists.txt.

Sources: CMakeLists.txt:52-60

This testing infrastructure provides the foundation for the "reconstruct incrementally" goal mentioned in the roadmap, allowing developers to verify small, testable pieces of the game system as they are ported to modern C++20.

Sources: README.md:38-42, CMakeLists.txt:13