Testing Strategy

We use Vitest for running unit and integration tests. Since our application involves complex chess logic, move parsing, and state transitions, tests are crucial for verifying that everything behaves correctly according to the Dice Chess rules.

1. Running Tests

You can run tests using mise or standard npm scripts:

# Run all tests once
mise run test

# Run tests in watch/interactive mode
npm run test:watch

2. Code Coverage

Code coverage is generated using @vitest/coverage-v8. You can check coverage metrics locally to ensure your changes are adequately tested:

# Run tests and generate coverage report
mise run test:coverage

The coverage report compiles into the coverage/ directory.

3. What is Tested?

The test suite covers both domain logic and reactive state management:

Engine Adapter: engine.test.ts validates that the frontend can parse standard chess FENs, format them into DFENs (Dice Chess FENs), and communicate with the @rabestro/dicechess-engine JS/WASM module correctly.
Game Reconstruction: reconstruction.test.ts ensures that game transcripts (sequential lists of dice rolls and micro-moves) can be correctly parsed and replayed to reconstruct the chessboard state at any point in the game.
Openings Explorer: explorer.test.ts verifies the logic for traversing the openings tree, sorting next moves, and calculating stats (wins/losses/draws) for different branches.
Reactive Stores: Tests under src/lib/stores/ verify that UI states (such as active game playback indices or filters) transition reactively.

4. Test Guidelines

When adding features or refactoring:

Write Unit Tests: For any new utilities or store actions, write a corresponding .test.ts file in the same directory.
Mock External APIs: Do not call live backend APIs. Mock data structures and network requests.
Verify Dice Rules: Ensure edge cases like the Maximum Micro-moves Rule (failing to make 3 moves when forced) or king capture scenarios are correctly handled in your test cases.