Testing and Quality Assurance

Relevant source files

• internal/application/bot.go
• internal/application/bot_test.go
• internal/application/test_utils_test.go
• internal/domain/game/round/board_renderer.go
• internal/domain/game/round/board_renderer_test.go
• internal/domain/game/round/service/shanten_test.go
• test/original_vs_port/compare/QA_REVIEW.md
• test/original_vs_port/compare/action.go
• test/original_vs_port/compare/action_test.go
• test/original_vs_port/compare/comparer.go
• test/original_vs_port/compare/comparer_test.go
• test/original_vs_port/compare/config.go
• test/original_vs_port/compare/main.go
• test/original_vs_port/compare/main_test.go
• test/original_vs_port/gen_log/akochan/Dockerfile
• test/original_vs_port/gen_log/akochan/patch.sh
• test/original_vs_port/gen_log/akochan/run_akochan.sh
• test/original_vs_port/gen_log/compose.yaml
• test/original_vs_port/gen_log/manue/run_manue.sh
• test/original_vs_port/gen_log/server/Dockerfile
• test/original_vs_port/gen_log/server/patch.sh
• test/original_vs_port/gen_log/server/run_server.sh

The mjai-manue-go project employs a multi-layered testing strategy to ensure the correctness of the Go port, maintain behavioral parity with the original CoffeeScript implementation, and verify the integrity of the Mahjong game logic. The suite ranges from low-level domain unit tests to complex integration frameworks involving Dockerized environments.

Testing Strategy Overview

The testing architecture is divided into three primary categories:

1. Domain and Runtime Verification: Unit tests for core logic (shanten, yaku, state transitions) and golden-file tests for the MJAI protocol driver.
2. Behavioral Equivalence: A comparison framework that runs the original CoffeeScript agent and the Go port against the same game logs to identify decision-making discrepancies.
3. End-to-End Simulation: Self-match scripts that facilitate large-scale game generation between multiple Go agent instances to stress-test the engine and generate statistical data.

---

Unit and Integration Tests

The codebase includes comprehensive unit tests for the internal/domain layer, covering tile primitives, hand analysis, and the round state machine. A significant portion of the integration testing is handled via Golden-File Tests within the MJAI runtime.

The internal/application package contains high-level tests for the Bot entity, ensuring that it correctly dispatches events to the domain and generates appropriate reactions (e.g., ReactionAction or ReactionNone) internal/application/bot_test.go17-103 Additionally, the round.State includes a BoardRenderer used in tests to visualize the board state in a human-readable format, facilitating easier debugging of complex game scenarios internal/domain/game/round/board_renderer_test.go12-47

Key Components:

• Bot Processing: Bot.Process is tested for various scenarios including self-draws, other-player draws, and Riichi acceptance internal/application/bot_test.go29-152
• Board Visualization: The RenderBoard function provides a text-based representation of the table, including hands, rivers (ho), and melds internal/domain/game/round/board_renderer.go19-49
• Shanten Analysis: Unit tests verify hand analysis logic, such as shanten calculation and wait detection internal/domain/game/round/service/shanten_test.go1-20
• Test Helpers: mustNewBotForTest and newValidHands provide standardized setups for application-level tests internal/application/test_utils_test.go15-61

For details, see Unit and Integration Tests.

---

Original-vs-Port Comparison Framework

To guarantee that the Go port behaves identically to the original mjai-manue, a specialized comparison framework resides in test/original_vs_port/. This framework identifies "divergence points" where the two implementations choose different actions given the same game state.

Original-vs-Port Comparison Flow

Sources: test/original_vs_port/compare/main.go40-58 test/original_vs_port/gen_log/compose.yaml15-45

Key Components:

• gen_log: A Docker Compose setup running the original CoffeeScript manue against akochan opponents to generate baseline logs test/original_vs_port/gen_log/compose.yaml27-45
• compare utility: A Go program that parses logs using inbound.ParseMessage test/original_vs_port/compare/comparer.go90-93 feeds them into ManueAgent.Decide, and compares the result with the original action recorded in the log test/original_vs_port/compare/comparer.go182-198
• Action Normalization: The normalizeRawAction function ensures that differences in JSON formatting or non-essential fields do not trigger false mismatches test/original_vs_port/compare/comparer.go96-101
• Preemption Logic: The framework accounts for Mahjong rules where a higher-priority action (like a Win/Hora) might preempt a lower-priority one (like a Chi), preventing incorrect mismatch reports test/original_vs_port/compare/comparer.go232-245

For details, see Original-vs-Port Comparison Framework.

---

Self-Match Log Generation

The scripts/self-match/ directory (and related Docker configurations) contains tools for running the Go agent against itself. This is primarily used for generating large volumes of data for the tools/ suite to process into game statistics (game_stats.json).

Key Components:

• Docker Orchestration: The compose.yaml defines services for the MJAI server, Go Manue instances, and Akochan instances for diverse testing environments test/original_vs_port/gen_log/compose.yaml15-45
• Environment Variables: NUM_GAMES, ROOM, and PORT are used to control the simulation parameters test/original_vs_port/gen_log/compose.yaml5-13
• Server Patching: The Ruby-based MJAI server is patched during the Docker build to ensure compatibility with modern Ruby versions and specific protocol requirements test/original_vs_port/gen_log/server/patch.sh1-19

For details, see Self-Match Log Generation.

---

Testing Infrastructure to Code Mapping

The following diagram maps the testing infrastructure to the specific code entities responsible for execution.

Sources: internal/application/bot_test.go17-27 test/original_vs_port/compare/comparer.go69-81 test/original_vs_port/gen_log/compose.yaml1-14