Testing.md

Testing

This page describes the testing framework for MicroChess, focusing on the unit tests implemented in test/unit_test_001.cpp. These tests ensure the reliability and correctness of core components, such as board representation, move generation, and game logic, within Arduino’s constrained environment (less than 2K RAM).

Overview

Testing is critical for verifying that MicroChess functions as intended, especially given the complexity of chess rules and the need for memory efficiency. The unit tests in test/unit_test_001.cpp validate key functionalities, helping developers identify and fix bugs while maintaining compatibility with Arduino’s resource limits.

Unit Testing Framework

MicroChess uses a lightweight unit testing approach tailored for Arduino:

• File: test/unit_test_001.cpp contains the test suite.
• Purpose: Tests core classes (board_t, move_t, game_t) and supporting functions.
• Execution: Tests are run on the Arduino or in a simulated environment (e.g., Arduino IDE with a testing framework like AUnit).
• Output: Results are printed to the Serial Monitor, indicating pass/fail status for each test.

Key Components Tested

• Board Representation (board.h/cpp):
  • Setting and getting pieces on squares.
  • Initial board setup (standard chess position).
  • Memory efficiency of spot_t bit fields.
• Move Generation (move.h/cpp):
  • Generating legal moves for each piece type (pawn, knight, etc.).
  • Handling special moves (castling, en passant, promotion).
  • Validating move legality (e.g., not moving into check).
• Game Logic (game.h/cpp):
  • Applying and undoing moves.
  • Detecting check, checkmate, and stalemate.
  • Tracking turn and move history.
• Evaluation (chessutil.cpp, pieces.cpp):
  • Correctness of material and positional scores.
  • Consistency of evaluation for mirrored positions.
• Utility Functions (chessutil.cpp, conv.h):
  • Conversion between algebraic notation and internal move formats.
  • Helper functions for board analysis.

Test Cases

The unit_test_001.cpp file includes test cases such as:

• Board Initialization:
  • Verify board_t::setup() creates the correct starting position (e.g., white rook on a1, black king on e8).
• Piece Movement:
  • Test pawn moves (e.g., e2e4, e2e3) and captures (e.g., e4d5).
  • Confirm knight jumps (e.g., g1f3) respect L-shape rules.
• Special Moves:
  • Validate castling conditions (king/rook unmoved, no check).
  • Test en passant eligibility after a two-square pawn move.
  • Ensure pawn promotion creates the correct piece (e.g., queen).
• Game State:
  • Check detection after moves exposing the king.
  • Confirm checkmate in known positions (e.g., fool’s mate).
  • Verify stalemate when no legal moves exist.
• Evaluation:
  • Test material balance in the starting position (score ≈ 0).
  • Verify positional bonuses (e.g., central pawn advantage).
• Move Validation:
  • Reject illegal moves (e.g., king moving two squares without castling).
  • Ensure moves leaving the king in check are blocked.

Running Tests

To run the unit tests:

1. Set Up the Environment:
   • Ensure the Arduino IDE is installed and the MicroChess project is loaded (see Installation).
   • (Optional) Install a testing framework like AUnit for enhanced test support.
2. Include Test File:
   • Add test/unit_test_001.cpp to the project folder or compile it separately.
3. Upload and Run:
   • Upload the test sketch to the Arduino.
   • Open the Serial Monitor (baud rate: 9600) to view test results.
4. Interpret Output:
   • Example output:

     Test 1: Board Setup - PASSED
     Test 2: Pawn Moves - PASSED
     Test 3: Checkmate Detection - FAILED
     ...
     Summary: 10/12 tests passed
     

   • Failed tests indicate areas needing debugging.

Optimization for Arduino

Testing is designed for efficiency:

• Minimal Overhead: Tests use compact data structures to fit within 2K RAM.
• Targeted Scope: Focuses on critical components to avoid excessive memory usage.
• Serial Output: Leverages the Serial Monitor for results, requiring no additional hardware.

Integration with Other Components

The tests interact with:

• Board Representation (board.h/cpp): Validates board_t functionality.
• Move Generation (move.h/cpp): Ensures move_t generates correct moves.
• Game Logic (game.h/cpp): Verifies game_t state transitions.
• Evaluation (chessutil.cpp): Checks scoring accuracy.
• Statistics (stats.h/cpp): May log test-related metrics (e.g., nodes searched during validation).

Example

A test case for pawn moves:

• Setup: Place a white pawn on e2 in an empty board.
• Test: Generate moves, expecting e2e3 and e2e4.
• Result: Pass if both moves are generated, fail if any are missing or invalid.

Visual Aids

Test results appear in:

• Serial Console: Shows pass/fail status (see MicroChessConsole2.gif).
• LED Strip: Unaffected by tests (see MicroChessSmall.gif). More details are in the Visuals page.

Next Steps

• See Contributing for how to add new tests.
• Explore Statistics for performance metrics.
• Check Code Structure for an overview of all files.

---

Back to Home | Next: Contributing