weevil/templates/testing/README.md.template

# FTC Robot Testing Showcase

A comprehensive FTC robot project demonstrating **professional testing without hardware**.

## What This Demonstrates

This project shows how to build testable FTC robots using:
- **Hardware abstraction** - Interfaces separate logic from FTC SDK
- **Unit testing** - Test individual components in isolation
- **System testing** - Test complete autonomous sequences
- **Edge case testing** - Sensor failures, noise, boundary conditions

**All tests run instantly on Windows - no robot needed!**

## The Robot Systems

### 1. Motor Cycler
Continuously cycles a motor (2s ON, 1s OFF) - demonstrates timing logic

### 2. Wall Approach
Safely approaches a wall using distance sensor:
- Drives fast when far away
- Slows down as it gets closer
- Stops at target distance
- Handles sensor failures

### 3. Turn Controller  
Turns robot to target heading using gyro:
- Proportional control (faster when far from target)
- Chooses shortest rotation path
- Handles 360° wraparound
- Compensates for drift

## Project Structure

```
src/main/java/robot/
├── hardware/                   # Hardware abstractions
│   ├── MotorController.java           # ✅ Interface
│   ├── DistanceSensor.java            # ✅ Interface
│   ├── GyroSensor.java                # ✅ Interface
│   ├── FtcMotorController.java        # ❌ FTC (excluded from tests)
│   ├── FtcDistanceSensor.java         # ❌ FTC (excluded from tests)
│   └── FtcGyroSensor.java             # ❌ FTC (excluded from tests)
│
├── subsystems/                 # Robot logic (pure Java!)
│   ├── MotorCycler.java               # ✅ Testable
│   ├── WallApproach.java              # ✅ Testable
│   └── TurnController.java            # ✅ Testable
│
└── opmodes/                    # FTC integration
    └── MotorCycleOpMode.java          # ❌ FTC (excluded from tests)

src/test/java/robot/
├── hardware/                   # Test mocks
│   ├── MockMotorController.java
│   ├── MockDistanceSensor.java
│   └── MockGyroSensor.java
│
└── subsystems/                 # Tests
    ├── MotorCyclerTest.java           # 8 tests
    ├── WallApproachTest.java          # 13 tests
    ├── TurnControllerTest.java        # 15 tests
    └── AutonomousIntegrationTest.java # 5 system tests
```

## Test Coverage

**41 Total Tests:**
- **Unit tests**: Individual component behaviors
- **System tests**: Complete autonomous missions  
- **Edge cases**: Sensor failures, noise, boundaries
- **Integration**: Multiple subsystems working together

Run time: **< 2 seconds on Windows!**

## Building and Testing

### Run Tests (Windows JRE)
```bash
gradlew test
```
Tests run on your local machine without requiring Android or FTC SDK.

### Build APK for Robot (requires FTC SDK)
```bash
build.bat        # Windows
./build.sh       # Linux/Mac
```

### Deploy to Robot
```bash
deploy.bat       # Windows  
./deploy.sh      # Linux/Mac
```

## Hardware Configuration

Configure your FTC robot with:
- DC Motors named `"left_motor"` and `"right_motor"`
- Distance sensor (REV 2m or similar)
- IMU/Gyro sensor

## Testing Showcase

### Unit Test Example: Wall Approach
```java
@Test
void testSlowsDownNearWall() {
    sensor.setDistance(25.0);  // 25cm from wall
    
    wallApproach.start();
    wallApproach.update();
    
    // Should slow down to 0.2 power
    assertEquals(0.2, leftMotor.getPower(), 0.001);
    assertEquals(WallApproachState.SLOWING, wallApproach.getState());
}
```

### System Test Example: Complete Mission
```java
@Test
void testCompleteAutonomousMission() {
    // Simulate entire autonomous:
    // 1. Drive to wall (100cm → 10cm)
    // 2. Turn 90° right
    // 3. Drive forward again
    // 4. Turn back to original heading
    
    // All without a robot! Tests run in ~100ms
}
```

### Edge Case Example: Sensor Failure
```java
@Test
void testSensorFailureHandling() {
    wallApproach.start();
    
    // Sensor suddenly fails!
    sensor.simulateFailure();
    wallApproach.update();
    
    // Should safely stop
    assertEquals(WallApproachState.ERROR, wallApproach.getState());
    assertEquals(0.0, motor.getPower());
}
```

## What Tests Cover

**Unit Tests** (test individual behaviors):
- Motor timing and power levels
- Distance threshold detection
- Turn angle calculations
- State transitions

**System Tests** (test complete scenarios):
- Full autonomous sequences
- Multi-waypoint navigation
- Square pattern driving
- Sensor coordination

**Edge Cases** (test failure modes):
- Sensor failures and recovery
- Noise handling
- Boundary conditions
- Wraparound math (0° ↔ 359°)

**All 41 tests run in < 2 seconds on Windows!**

## The Pattern: Applies to Any Hardware

Same pattern works for **anything**:

### Servo Example
```java
// Interface
public interface ServoController {
    void setPosition(double position);
}

// FTC impl (excluded from tests)
public class FtcServoController implements ServoController {
    private final Servo servo;  // FTC SDK class
    ...
}

// Mock (for tests)
public class MockServoController implements ServoController {
    private double position = 0.5;
    ...
}
```

See `TESTING_GUIDE.md` for more examples (sensors, encoders, vision, etc.)

## How It Works

The architecture demonstrates three layers:

1. **Hardware Abstraction** (`MotorController` interface)
   - Defines what a motor can do
   - Allows swapping implementations (real motor vs. mock)

2. **Business Logic** (`MotorCycler` class)  
   - Implements the cycling behavior
   - Completely independent of FTC SDK
   - Fully testable with mocks

3. **Integration** (`MotorCycleOpMode`)
   - Wires everything together
   - Minimal code, just connects the pieces

## Why This Matters

Traditional FTC projects force you to edit SDK files directly and make testing difficult. 
Weevil's approach:
- ✓ Keep your code separate from the SDK
- ✓ Write unit tests that run instantly on your PC
- ✓ Build more reliable robots faster
- ✓ Learn better software engineering practices