# 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:

```javascript
runTests();
```

Or use the provided script:

```javascript
// 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`):

```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:
```cpp
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