screeps/douwco_hivemind/test/README.md

Douwco Hivemind Testing Framework

Overview

This testing framework allows you to verify the logic of your Screeps C++ code before uploading it to the live server. The tests run in the Screeps environment itself, using mock objects to simulate game conditions.

Running Tests

In Screeps Console

1. Upload your compiled WASM module as usual
2. Open the Screeps console
3. Paste the following command:

runTests();

Or use the provided script:

// Copy the contents of run_tests.js and paste into console

Expected Output

The tests will output results in this format:

=== Running Douwco Hivemind Tests ===

--- Running Creep Base Tests ---
[PASS] CreepBase::Initialization with memory
[PASS] CreepBase::isNearTo() distance 1
[PASS] CreepBase::isNearTo() distance 2
[PASS] CreepBase::isNearTo() distance 3
[PASS] CreepBase::Memory management

--- Running Worker Tests ---
[PASS] Worker::Initialization with harvesting state
[PASS] Worker::Empty creep starts harvesting
[PASS] Worker::Harvesting state when empty

=== Test Results ===
Passed: 8/8
Failed: 0/8
Success Rate: 100%

Test Structure

Test Categories

• Creep Tests: Base creep functionality (movement, memory, targeting)
• Worker Tests: Worker-specific logic (harvesting, state management)
• Supplier Tests: Supplier role behavior
• Path Tests: Pathfinding utilities
• Spawn Tests: Spawn decision algorithms
• Utility Tests: Helper functions

Current Test Coverage

Component	Test Coverage	Status
CreepBase	80%	✅ Implemented
Worker	60%	✅ Basic tests
Supplier	20%	🟡 Placeholder
Path Tools	10%	🟡 Placeholder
Spawn Logic	10%	🟡 Placeholder
Utilities	10%	🟡 Placeholder

Adding New Tests

Test File Structure

1. Test Files: Located in src/Testing/
2. Mock Objects: Defined in include/Testing/Mocks.hpp
3. Test Harness: Testing/TestHarness.hpp/cpp

Creating a New Test

1. Add test function to the appropriate test file (e.g., CreepTests.cpp):

void testNewFeature()
{
    // Arrange
    Mocks::MockCreep mockCreep("TestCreep");
    mockCreep.setPosition(10, 10);
    
    // Act
    CreepBase creep(mockCreep);
    bool result = creep.someFunction();
    
    // Assert
    TestResult testResult("CreepBase::New feature test", 
                         result == expectedValue,
                         "Feature did not work as expected");
    addTestResult(testResult);
}

2. Call the test from the appropriate runXXXTests() function

3. Add mocks if needed in Mocks.hpp

Creating Mock Objects

The framework includes mock implementations of key Screeps classes:

• MockCreep: Simulates creep behavior
• MockRoomPosition: Position tracking
• MockStore: Resource management
• MockSource: Energy source simulation

Example:

Mocks::MockCreep mockCreep("TestCreep");
mockCreep.setPosition(10, 10);
mockCreep.setEnergy(50);

Test Development Roadmap

High Priority Tests to Implement

1. Worker State Machine: Complete harvesting/depositing transitions
2. Supplier Targeting: Energy structure selection logic
3. Pathfinding: Edge cases and obstacle handling
4. Spawn Calculations: Creep requirement algorithms
5. Memory Management: Complex memory operations

Medium Priority

1. Performance Tests: CPU usage measurements
2. Edge Cases: Boundary conditions
3. Error Handling: Invalid inputs and error states

Building with Tests

The test framework is automatically included in the build process. No special build steps are required.

Limitations

1. Screeps API Dependency: Some functionality cannot be fully mocked
2. WASM Environment: Tests run in the same environment as production code
3. Performance Impact: Running comprehensive tests may use significant CPU

Best Practices

1. Run tests frequently during development
2. Add tests for new features before implementation
3. Test edge cases and error conditions
4. Keep tests fast to avoid CPU bucket issues
5. Clean up test memory to avoid polluting game state

Troubleshooting

Issue: runTests is not defined Solution: Ensure the WASM module is properly loaded and the latest version is uploaded

Issue: Tests failing in Screeps but passing locally Solution: Check for differences between mock behavior and actual Screeps API

Issue: High CPU usage from tests Solution: Reduce test complexity or run tests less frequently