feat: Add template system to weevil new command
Implements template-based project creation allowing teams to start with
professional example code instead of empty projects.
Features:
- Two templates: 'basic' (minimal) and 'testing' (45-test showcase)
- Template variable substitution ({{PROJECT_NAME}}, etc.)
- Template validation with helpful error messages
- `weevil new --list-templates` command
- Template files embedded in binary at compile time
Technical details:
- Templates stored in templates/basic/ and templates/testing/
- Files ending in .template have variables replaced
- Uses include_dir! macro to embed templates in binary
- Returns file count for user feedback
Testing template includes:
- 3 complete subsystems (MotorCycler, WallApproach, TurnController)
- Hardware abstraction layer with mock implementations
- 45 comprehensive tests (unit, integration, system)
- Professional documentation (DESIGN_AND_TEST_PLAN.md, etc.)
Usage:
weevil new my-robot # basic template
weevil new my-robot --template testing # testing showcase
weevil new --list-templates # show available templates
This enables FTC teams to learn from working code and best practices
rather than starting from scratch.
This commit is contained in:
Eric Ratliff
975
templates/testing/DESIGN_AND_TEST_PLAN.md
Normal file
975
templates/testing/DESIGN_AND_TEST_PLAN.md
Normal file
@@ -0,0 +1,975 @@
|
||||
# FTC Robot System Design & Test Plan
|
||||
|
||||
## Document Overview
|
||||
|
||||
This document defines the system architecture, component responsibilities, and comprehensive test strategy for the FTC robot project. It serves as the authoritative reference for understanding how the system is structured and how tests validate each component.
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** February 2026
|
||||
**Status:** Implementation Complete, All Tests Passing
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Architecture](#system-architecture)
|
||||
2. [Component Specifications](#component-specifications)
|
||||
3. [Interface Contracts](#interface-contracts)
|
||||
4. [Test Strategy](#test-strategy)
|
||||
5. [Test Coverage Matrix](#test-coverage-matrix)
|
||||
6. [Test Cases by Component](#test-cases-by-component)
|
||||
7. [Integration Test Scenarios](#integration-test-scenarios)
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
### High-Level System Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ FTC ROBOT SYSTEM │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────┐
|
||||
│ OpMode Layer │ ← FTC Integration
|
||||
│ (Robot Only) │
|
||||
└──────────────────────┘
|
||||
↓
|
||||
┌─────────────────────┴─────────────────────┐
|
||||
│ │
|
||||
┌───────▼───────┐ ┌──────────▼─────────┐ ┌───────▼────────┐
|
||||
│ MotorCycler │ │ WallApproach │ │ TurnController │
|
||||
│ Subsystem │ │ Subsystem │ │ Subsystem │
|
||||
└───────┬───────┘ └────────┬───────────┘ └────────┬───────┘
|
||||
│ │ │
|
||||
│ ┌───────┴────────┐ │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Hardware Abstraction Layer │
|
||||
│ (Interfaces - No FTC Dependencies) │
|
||||
│ │
|
||||
│ • MotorController • DistanceSensor • GyroSensor │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
│ │ │
|
||||
└───────────────────┴────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ │
|
||||
TEST MODE ROBOT MODE
|
||||
│ │
|
||||
┌───────▼───────┐ ┌─────────▼─────────┐
|
||||
│ Test Mocks │ │ FTC Wrappers │
|
||||
│ │ │ │
|
||||
│ • MockMotor │ │ • FtcMotor │
|
||||
│ • MockDist │ │ • FtcDistance │
|
||||
│ • MockGyro │ │ • FtcGyro │
|
||||
│ │ │ │
|
||||
│ (Variables) │ │ (Real Hardware) │
|
||||
└───────────────┘ └───────────────────┘
|
||||
```
|
||||
|
||||
### Layer Responsibilities
|
||||
|
||||
| Layer | Purpose | Dependencies | Testability |
|
||||
|-------|---------|--------------|-------------|
|
||||
| **OpMode** | FTC SDK integration, hardware initialization | FTC SDK | Not tested (trivial glue code) |
|
||||
| **Subsystems** | Robot behavior logic, state machines, control | Interfaces only | ✅ 100% tested |
|
||||
| **Interfaces** | Hardware abstraction contracts | None (pure interfaces) | ✅ Contracts verified |
|
||||
| **FTC Wrappers** | Thin hardware adapters | FTC SDK | Not tested (3-5 line wrappers) |
|
||||
| **Test Mocks** | Test doubles for hardware | Interfaces only | ✅ Used in all tests |
|
||||
|
||||
### Data Flow: Test Mode vs Robot Mode
|
||||
|
||||
```
|
||||
TEST MODE: ROBOT MODE:
|
||||
═══════════ ════════════
|
||||
|
||||
Test Case OpMode.loop()
|
||||
↓ ↓
|
||||
Set Mock State Read Hardware Map
|
||||
↓ ↓
|
||||
Call Subsystem FTC Wrapper
|
||||
↓ ↓
|
||||
Subsystem Logic ←──────── SAME CODE ──────────→ Subsystem Logic
|
||||
↓ ↓
|
||||
Call Interface Method Call Interface Method
|
||||
↓ ↓
|
||||
Mock Returns Value FTC Wrapper Reads I2C/PWM
|
||||
↓ ↓
|
||||
Subsystem Continues Subsystem Continues
|
||||
↓ ↓
|
||||
Assert Result Robot Moves
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Specifications
|
||||
|
||||
### 1. MotorCycler Subsystem
|
||||
|
||||
**Purpose:** Demonstrate time-based control and state machines
|
||||
|
||||
**Responsibilities:**
|
||||
- Cycle motor ON/OFF at configurable intervals
|
||||
- Track elapsed time in current state
|
||||
- Provide state information for telemetry
|
||||
- Support start/stop control
|
||||
|
||||
**States:**
|
||||
```
|
||||
┌──────┐
|
||||
│ OFF │ ←──┐
|
||||
└───┬──┘ │
|
||||
│ │
|
||||
[offDurationMs elapsed]
|
||||
│ │
|
||||
▼ │
|
||||
┌──────┐ │
|
||||
│ ON │ ──┘
|
||||
└──────┘
|
||||
[onDurationMs elapsed]
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
- `onDurationMs`: Time to stay ON (default: 2000ms)
|
||||
- `offDurationMs`: Time to stay OFF (default: 1000ms)
|
||||
- `motorPower`: Power level when ON (default: 0.5)
|
||||
|
||||
**Dependencies:**
|
||||
- `MotorController` (interface)
|
||||
|
||||
**Key Methods:**
|
||||
- `init()`: Initialize to OFF state
|
||||
- `update(long currentTimeMs)`: Update state based on elapsed time
|
||||
- `stop()`: Force stop and reset to OFF
|
||||
- `getState()`: Current state (ON/OFF)
|
||||
- `getTimeInState(long currentTime)`: Time spent in current state
|
||||
|
||||
---
|
||||
|
||||
### 2. WallApproach Subsystem
|
||||
|
||||
**Purpose:** Safely approach obstacles using distance feedback with speed ramping
|
||||
|
||||
**Responsibilities:**
|
||||
- Drive toward wall at safe speed
|
||||
- Slow down as approaching target distance
|
||||
- Emergency stop if too close
|
||||
- Handle sensor failures gracefully
|
||||
- Coordinate left/right motor speeds
|
||||
|
||||
**States:**
|
||||
```
|
||||
┌──────┐
|
||||
│ INIT │
|
||||
└───┬──┘
|
||||
│ start()
|
||||
▼
|
||||
┌────────────┐
|
||||
│ APPROACHING│ ←────────┐
|
||||
└─────┬──────┘ │
|
||||
│ │
|
||||
[distance < 30cm] [distance > 30cm]
|
||||
│ │
|
||||
▼ │
|
||||
┌────────┐ │
|
||||
│ SLOWING│ ─────────────┘
|
||||
└────┬───┘
|
||||
│
|
||||
[distance < 10cm]
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│ STOPPED │
|
||||
└─────────┘
|
||||
|
||||
[sensor invalid]
|
||||
↓
|
||||
┌────────┐
|
||||
│ ERROR │
|
||||
└────────┘
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
- `STOP_DISTANCE_CM`: Target stop distance (10cm)
|
||||
- `SLOW_DISTANCE_CM`: Begin slowing threshold (30cm)
|
||||
- `FAST_SPEED`: Full speed power (0.6)
|
||||
- `SLOW_SPEED`: Reduced speed power (0.2)
|
||||
|
||||
**Dependencies:**
|
||||
- `DistanceSensor` (interface)
|
||||
- `MotorController` x2 (left/right)
|
||||
|
||||
**Key Methods:**
|
||||
- `start()`: Begin approach sequence
|
||||
- `update()`: State machine update
|
||||
- `stop()`: Emergency stop
|
||||
- `getState()`: Current state
|
||||
- `getCurrentDistance()`: Current sensor reading
|
||||
- `hasSensorError()`: Error flag status
|
||||
|
||||
---
|
||||
|
||||
### 3. TurnController Subsystem
|
||||
|
||||
**Purpose:** Rotate robot to target heading using gyro feedback with proportional control
|
||||
|
||||
**Responsibilities:**
|
||||
- Turn to specified heading (0-359°)
|
||||
- Choose shortest rotation path
|
||||
- Apply proportional control (faster when far from target)
|
||||
- Handle 360° wraparound math
|
||||
- Detect completion within tolerance
|
||||
|
||||
**States:**
|
||||
```
|
||||
┌──────┐
|
||||
│ IDLE │
|
||||
└───┬──┘
|
||||
│ turnTo(heading)
|
||||
▼
|
||||
┌─────────┐
|
||||
│ TURNING │
|
||||
└────┬────┘
|
||||
│
|
||||
[error < tolerance]
|
||||
│
|
||||
▼
|
||||
┌──────────┐
|
||||
│ COMPLETE │
|
||||
└──────────┘
|
||||
```
|
||||
|
||||
**Control Algorithm:**
|
||||
```
|
||||
error = shortestAngle(current, target)
|
||||
power = error × KP
|
||||
power = clamp(power, MIN_TURN_POWER, MAX_TURN_POWER)
|
||||
leftMotor = power
|
||||
rightMotor = -power
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
- `HEADING_TOLERANCE`: Success threshold (2.0°)
|
||||
- `MIN_TURN_POWER`: Minimum power (0.15)
|
||||
- `MAX_TURN_POWER`: Maximum power (0.5)
|
||||
- `KP`: Proportional gain (0.02)
|
||||
|
||||
**Dependencies:**
|
||||
- `GyroSensor` (interface)
|
||||
- `MotorController` x2 (left/right)
|
||||
|
||||
**Key Methods:**
|
||||
- `turnTo(double targetDegrees)`: Start turn
|
||||
- `update()`: Control loop update
|
||||
- `stop()`: Halt turning
|
||||
- `getState()`: Current state
|
||||
- `getHeadingError()`: Degrees from target
|
||||
- `getCurrentHeading()`: Current gyro reading
|
||||
|
||||
---
|
||||
|
||||
## Interface Contracts
|
||||
|
||||
### MotorController Interface
|
||||
|
||||
**Contract:** Abstract motor control with power setting and reading
|
||||
|
||||
```java
|
||||
public interface MotorController {
|
||||
/**
|
||||
* Set motor power.
|
||||
* @param power Range: -1.0 (full reverse) to +1.0 (full forward)
|
||||
*/
|
||||
void setPower(double power);
|
||||
|
||||
/**
|
||||
* Get current motor power setting.
|
||||
* @return Current power (-1.0 to +1.0)
|
||||
*/
|
||||
double getPower();
|
||||
}
|
||||
```
|
||||
|
||||
**Implementations:**
|
||||
- `FtcMotorController`: Wraps `DcMotor` from FTC SDK
|
||||
- `MockMotorController`: Test double, stores power in variable
|
||||
|
||||
**Invariants:**
|
||||
- Power values should be clamped to [-1.0, 1.0]
|
||||
- `getPower()` should return last value set by `setPower()`
|
||||
|
||||
---
|
||||
|
||||
### DistanceSensor Interface
|
||||
|
||||
**Contract:** Abstract distance measurement
|
||||
|
||||
```java
|
||||
public interface DistanceSensor {
|
||||
/**
|
||||
* Get distance reading in centimeters.
|
||||
* @return Distance in cm, or -1 if error
|
||||
*/
|
||||
double getDistanceCm();
|
||||
|
||||
/**
|
||||
* Check if sensor has valid data.
|
||||
* @return true if working properly
|
||||
*/
|
||||
boolean isValid();
|
||||
}
|
||||
```
|
||||
|
||||
**Implementations:**
|
||||
- `FtcDistanceSensor`: Wraps REV 2m Distance Sensor
|
||||
- `MockDistanceSensor`: Test double, configurable distance/noise/failure
|
||||
|
||||
**Invariants:**
|
||||
- Valid readings should be in range [0, 8190] cm
|
||||
- `isValid()` returns false when `getDistanceCm()` returns -1
|
||||
|
||||
---
|
||||
|
||||
### GyroSensor Interface
|
||||
|
||||
**Contract:** Abstract heading measurement
|
||||
|
||||
```java
|
||||
public interface GyroSensor {
|
||||
/**
|
||||
* Get current heading.
|
||||
* @return Heading in degrees (0-359)
|
||||
*/
|
||||
double getHeading();
|
||||
|
||||
/**
|
||||
* Reset heading to zero.
|
||||
*/
|
||||
void reset();
|
||||
|
||||
/**
|
||||
* Check calibration status.
|
||||
* @return true if calibrated and ready
|
||||
*/
|
||||
boolean isCalibrated();
|
||||
}
|
||||
```
|
||||
|
||||
**Implementations:**
|
||||
- `FtcGyroSensor`: Wraps REV Hub IMU
|
||||
- `MockGyroSensor`: Test double, configurable heading/drift
|
||||
|
||||
**Invariants:**
|
||||
- Heading should be normalized to [0, 360) range
|
||||
- `isCalibrated()` must be true before readings are reliable
|
||||
|
||||
---
|
||||
|
||||
## Test Strategy
|
||||
|
||||
### Testing Pyramid
|
||||
|
||||
```
|
||||
┌──────────┐
|
||||
│ E2E │ (5 tests)
|
||||
│ System │ - Complete missions
|
||||
└──────────┘ - Multi-subsystem
|
||||
╱ ╲
|
||||
╱ ╲
|
||||
╱ Integration ╲ (3 tests)
|
||||
╱ (Component) ╲ - Realistic scenarios
|
||||
╱ ╲- Noise, variance
|
||||
└──────────────────────┘
|
||||
╱ ╲
|
||||
╱ ╲
|
||||
╱ Unit Tests ╲ (37 tests)
|
||||
╱ (Isolated Behaviors) ╲ - State transitions
|
||||
╱ ╲- Calculations
|
||||
└──────────────────────────────────┘- Edge cases
|
||||
```
|
||||
|
||||
### Test Levels
|
||||
|
||||
| Level | Count | Purpose | Execution Time |
|
||||
|-------|-------|---------|----------------|
|
||||
| **Unit** | 37 | Test individual component behaviors in isolation | < 1 second |
|
||||
| **Integration** | 3 | Test realistic scenarios with noise/variance | < 0.5 seconds |
|
||||
| **System** | 5 | Test complete missions with multiple subsystems | < 1 second |
|
||||
| **Total** | 45 | Complete validation suite | < 2 seconds |
|
||||
|
||||
### Test Categories
|
||||
|
||||
**Functional Tests:**
|
||||
- State machine transitions
|
||||
- Control algorithms
|
||||
- Calculations and logic
|
||||
- API contracts
|
||||
|
||||
**Non-Functional Tests:**
|
||||
- Edge cases (boundaries, wraparound)
|
||||
- Error handling (sensor failures)
|
||||
- Robustness (noise, drift)
|
||||
- Performance (loop timing)
|
||||
|
||||
**System Tests:**
|
||||
- Complete autonomous sequences
|
||||
- Multi-subsystem coordination
|
||||
- Mission scenarios
|
||||
- Failure recovery
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage Matrix
|
||||
|
||||
### Coverage by Component
|
||||
|
||||
| Component | Unit Tests | Integration Tests | System Tests | Total | LOC | Coverage |
|
||||
|-----------|------------|-------------------|--------------|-------|-----|----------|
|
||||
| MotorCycler | 8 | 0 | 0 | 8 | 106 | 100% |
|
||||
| WallApproach | 13 | 1 | 0 | 14 | 130 | 100% |
|
||||
| TurnController | 15 | 0 | 0 | 15 | 140 | 100% |
|
||||
| System Integration | 0 | 0 | 5 | 5 | N/A | N/A |
|
||||
| Mock Hardware | 0 | 2 | 3 | 5 | 85 | 100% |
|
||||
| **Totals** | **36** | **3** | **5** | **45** | **461** | **100%** |
|
||||
|
||||
### Coverage by Feature
|
||||
|
||||
| Feature | Test Cases | Status |
|
||||
|---------|------------|--------|
|
||||
| Motor timing control | 8 | ✅ All pass |
|
||||
| Distance-based speed control | 7 | ✅ All pass |
|
||||
| Sensor failure handling | 3 | ✅ All pass |
|
||||
| Turn angle calculations | 6 | ✅ All pass |
|
||||
| Proportional control | 3 | ✅ All pass |
|
||||
| State machine transitions | 12 | ✅ All pass |
|
||||
| Wraparound math (0°↔359°) | 4 | ✅ All pass |
|
||||
| Emergency stops | 3 | ✅ All pass |
|
||||
| Complete missions | 5 | ✅ All pass |
|
||||
|
||||
---
|
||||
|
||||
## Test Cases by Component
|
||||
|
||||
### MotorCycler Tests (8 tests)
|
||||
|
||||
#### Unit Tests
|
||||
|
||||
**MC-01: Initial State Verification**
|
||||
- **Purpose:** Verify subsystem initializes to correct state
|
||||
- **Setup:** Create MotorCycler with 100ms ON, 50ms OFF
|
||||
- **Action:** Call `init()`
|
||||
- **Assert:** State = OFF, motor power = 0.0
|
||||
- **Rationale:** Ensures safe startup (motor off)
|
||||
|
||||
**MC-02: OFF→ON Transition**
|
||||
- **Purpose:** Verify state transition after OFF period
|
||||
- **Setup:** Initialize, advance time 50ms (past OFF duration)
|
||||
- **Action:** Call `update()`
|
||||
- **Assert:** State = ON, motor power = 0.75
|
||||
- **Rationale:** Tests timing logic and state machine
|
||||
|
||||
**MC-03: ON→OFF Transition**
|
||||
- **Purpose:** Verify state transition after ON period
|
||||
- **Setup:** Initialize, advance to ON state, advance 100ms
|
||||
- **Action:** Call `update()`
|
||||
- **Assert:** State = OFF, motor power = 0.0
|
||||
- **Rationale:** Completes cycle verification
|
||||
|
||||
**MC-04: Complete Cycle Sequence**
|
||||
- **Purpose:** Verify multiple state transitions
|
||||
- **Setup:** Initialize, advance through OFF→ON→OFF→ON
|
||||
- **Action:** Multiple `update()` calls with time advancement
|
||||
- **Assert:** Correct states and powers at each step
|
||||
- **Rationale:** Tests sustained operation
|
||||
|
||||
**MC-05: Time-in-State Tracking**
|
||||
- **Purpose:** Verify elapsed time calculation
|
||||
- **Setup:** Initialize, advance 25ms
|
||||
- **Action:** Call `getTimeInState()`
|
||||
- **Assert:** Returns 25ms
|
||||
- **Rationale:** Tests telemetry support
|
||||
|
||||
**MC-06: Emergency Stop**
|
||||
- **Purpose:** Verify manual stop functionality
|
||||
- **Setup:** Initialize, reach ON state
|
||||
- **Action:** Call `stop()`
|
||||
- **Assert:** State = OFF, motor power = 0.0
|
||||
- **Rationale:** Tests safety override
|
||||
|
||||
**MC-07: Default Power Configuration**
|
||||
- **Purpose:** Verify default power value (0.5)
|
||||
- **Setup:** Create with 2-arg constructor
|
||||
- **Action:** Advance to ON state
|
||||
- **Assert:** Motor power = 0.5
|
||||
- **Rationale:** Tests configuration defaults
|
||||
|
||||
**MC-08: Custom Power Configuration**
|
||||
- **Purpose:** Verify custom power setting
|
||||
- **Setup:** Create with power = 0.01
|
||||
- **Action:** Advance to ON state
|
||||
- **Assert:** Motor power = 0.01
|
||||
- **Rationale:** Tests configuration flexibility
|
||||
|
||||
---
|
||||
|
||||
### WallApproach Tests (14 tests)
|
||||
|
||||
#### Unit Tests
|
||||
|
||||
**WA-01: Initial State**
|
||||
- **Purpose:** Verify initialization
|
||||
- **Assert:** State = INIT
|
||||
- **Rationale:** Safe starting condition
|
||||
|
||||
**WA-02: Start Transition**
|
||||
- **Purpose:** Verify start command
|
||||
- **Action:** Call `start()`
|
||||
- **Assert:** State = APPROACHING
|
||||
- **Rationale:** Proper state machine entry
|
||||
|
||||
**WA-03: Full Speed When Far**
|
||||
- **Purpose:** Test speed selection at distance
|
||||
- **Setup:** Distance = 100cm
|
||||
- **Assert:** Motor power = 0.6, State = APPROACHING
|
||||
- **Rationale:** Optimal speed for long distances
|
||||
|
||||
**WA-04: Slow Speed When Near**
|
||||
- **Purpose:** Test speed reduction near target
|
||||
- **Setup:** Distance = 25cm (< 30cm threshold)
|
||||
- **Assert:** Motor power = 0.2, State = SLOWING
|
||||
- **Rationale:** Safety deceleration
|
||||
|
||||
**WA-05: Stop at Target**
|
||||
- **Purpose:** Test final stop condition
|
||||
- **Setup:** Distance = 10cm (at target)
|
||||
- **Assert:** Motor power = 0.0, State = STOPPED
|
||||
- **Rationale:** Precise positioning
|
||||
|
||||
**WA-06: Emergency Stop If Too Close**
|
||||
- **Purpose:** Test immediate stop when starting too close
|
||||
- **Setup:** Distance = 5cm (< stop threshold)
|
||||
- **Action:** Call `start()`, `update()`
|
||||
- **Assert:** State = STOPPED immediately
|
||||
- **Rationale:** Safety override
|
||||
|
||||
**WA-07: Sensor Failure Handling**
|
||||
- **Purpose:** Test error detection
|
||||
- **Setup:** Running approach, sensor fails
|
||||
- **Action:** Call `simulateFailure()`, `update()`
|
||||
- **Assert:** State = ERROR, motors = 0.0
|
||||
- **Rationale:** Graceful degradation
|
||||
|
||||
**WA-08: Recovery from Pushback**
|
||||
- **Purpose:** Test state reversal if pushed backward
|
||||
- **Setup:** In SLOWING state (25cm), pushed to 35cm
|
||||
- **Action:** Call `update()`
|
||||
- **Assert:** State = APPROACHING, speed = 0.6
|
||||
- **Rationale:** Adaptive behavior
|
||||
|
||||
**WA-09: Stays Stopped**
|
||||
- **Purpose:** Test final state persistence
|
||||
- **Setup:** Reach STOPPED state
|
||||
- **Action:** Multiple `update()` calls
|
||||
- **Assert:** Remains STOPPED
|
||||
- **Rationale:** Stable final state
|
||||
|
||||
**WA-10: Manual Stop Override**
|
||||
- **Purpose:** Test emergency stop command
|
||||
- **Setup:** Running at any state
|
||||
- **Action:** Call `stop()`
|
||||
- **Assert:** Motors = 0.0
|
||||
- **Rationale:** Safety control
|
||||
|
||||
**WA-11: Threshold Boundaries**
|
||||
- **Purpose:** Test exact boundary values
|
||||
- **Setup:** Test at 30.1cm, 29.9cm, 10.1cm, 9.9cm
|
||||
- **Assert:** Correct state transitions at boundaries
|
||||
- **Rationale:** Precision verification
|
||||
|
||||
#### System Test
|
||||
|
||||
**WA-12: Complete Approach Sequence**
|
||||
- **Purpose:** Test full approach from far to stopped
|
||||
- **Setup:** Start at 100cm
|
||||
- **Action:** Simulate approach with speed ramping
|
||||
- **Assert:** Transitions through all states, stops at target
|
||||
- **Rationale:** End-to-end validation
|
||||
|
||||
**WA-13: Sensor Noise Handling**
|
||||
- **Purpose:** Test robustness to noisy readings
|
||||
- **Setup:** Distance = 50cm, noise = ±2cm
|
||||
- **Action:** 20 updates with random noise
|
||||
- **Assert:** No erratic behavior, smooth operation
|
||||
- **Rationale:** Real-world reliability
|
||||
|
||||
#### Integration Test
|
||||
|
||||
**WA-14: Realistic Approach with Variance**
|
||||
- **Purpose:** Test complete approach with realistic conditions
|
||||
- **Setup:** Start 80cm away, ±1.5cm noise, variable speeds
|
||||
- **Action:** Simulate until stopped
|
||||
- **Assert:** Successfully stops near target, no crashes
|
||||
- **Rationale:** Real-world scenario validation
|
||||
|
||||
---
|
||||
|
||||
### TurnController Tests (15 tests)
|
||||
|
||||
#### Unit Tests
|
||||
|
||||
**TC-01: Initial State**
|
||||
- **Assert:** State = IDLE
|
||||
- **Rationale:** Proper initialization
|
||||
|
||||
**TC-02: TurnTo Activation**
|
||||
- **Action:** Call `turnTo(90)`
|
||||
- **Assert:** State = TURNING, target = 90°
|
||||
- **Rationale:** Command handling
|
||||
|
||||
**TC-03: Completion Detection**
|
||||
- **Setup:** Heading = 88.5°, target = 90°
|
||||
- **Assert:** State = COMPLETE (within 2° tolerance)
|
||||
- **Rationale:** Tolerance-based success
|
||||
|
||||
#### Path Selection Tests
|
||||
|
||||
**TC-04: Simple Clockwise (0°→90°)**
|
||||
- **Setup:** Current = 0°, target = 90°
|
||||
- **Assert:** Left motor positive, right motor negative
|
||||
- **Rationale:** Correct rotation direction
|
||||
|
||||
**TC-05: Simple Counter-Clockwise (90°→0°)**
|
||||
- **Setup:** Current = 90°, target = 0°
|
||||
- **Assert:** Left motor negative, right motor positive
|
||||
- **Rationale:** Correct rotation direction
|
||||
|
||||
**TC-06: Wraparound Clockwise (350°→10°)**
|
||||
- **Setup:** Current = 350°, target = 10°
|
||||
- **Assert:** Error = +20° (clockwise is shorter)
|
||||
- **Rationale:** Optimal path through 0°
|
||||
|
||||
**TC-07: Wraparound Counter-Clockwise (10°→350°)**
|
||||
- **Setup:** Current = 10°, target = 350°
|
||||
- **Assert:** Error = -20° (CCW is shorter)
|
||||
- **Rationale:** Optimal path through 0°
|
||||
|
||||
**TC-08: Opposite Heading (180° Ambiguous)**
|
||||
- **Setup:** Current = 0°, target = 180°
|
||||
- **Assert:** Error magnitude = 180°
|
||||
- **Rationale:** Either direction valid
|
||||
|
||||
#### Control Algorithm Tests
|
||||
|
||||
**TC-09: Proportional Power**
|
||||
- **Purpose:** Test power scales with error
|
||||
- **Setup:** Test large error (90°) vs small error (5°)
|
||||
- **Assert:** Large error → large power, small error → small power
|
||||
- **Rationale:** P-controller verification
|
||||
|
||||
**TC-10: Minimum Power Enforcement**
|
||||
- **Setup:** Very small error (just above tolerance)
|
||||
- **Assert:** Power ≥ 0.15 (minimum)
|
||||
- **Rationale:** Overcome friction
|
||||
|
||||
**TC-11: Maximum Power Cap**
|
||||
- **Setup:** Very large error (179°)
|
||||
- **Assert:** Power ≤ 0.5 (maximum)
|
||||
- **Rationale:** Safety limit
|
||||
|
||||
#### System Tests
|
||||
|
||||
**TC-12: Complete 90° Turn**
|
||||
- **Purpose:** Full turn execution
|
||||
- **Action:** Simulate turn with gyro feedback
|
||||
- **Assert:** Reaches target within tolerance
|
||||
- **Rationale:** Closed-loop validation
|
||||
|
||||
**TC-13: Complete Wraparound Turn**
|
||||
- **Purpose:** Test wraparound path
|
||||
- **Setup:** 350° → 10°
|
||||
- **Action:** Simulate turn
|
||||
- **Assert:** Completes via shortest path
|
||||
- **Rationale:** Math correctness
|
||||
|
||||
#### Edge Cases
|
||||
|
||||
**TC-14: Uncalibrated Gyro**
|
||||
- **Setup:** Set gyro uncalibrated
|
||||
- **Action:** Attempt turn
|
||||
- **Assert:** Returns to IDLE, motors stopped
|
||||
- **Rationale:** Safety check
|
||||
|
||||
**TC-15: Gyro Drift During Turn**
|
||||
- **Setup:** Drift = 0.5°/sec
|
||||
- **Action:** Simulate turn with drift
|
||||
- **Assert:** Compensates and completes
|
||||
- **Rationale:** Real-world robustness
|
||||
|
||||
**TC-16: Sequential Turns**
|
||||
- **Purpose:** Multiple turns without reset
|
||||
- **Action:** Turn 0→90→180→0
|
||||
- **Assert:** All complete successfully
|
||||
- **Rationale:** Continuous operation
|
||||
|
||||
**TC-17: Manual Stop**
|
||||
- **Setup:** Mid-turn
|
||||
- **Action:** Call `stop()`
|
||||
- **Assert:** Motors = 0.0
|
||||
- **Rationale:** Safety override
|
||||
|
||||
**TC-18: No-Op Turn (Already at Target)**
|
||||
- **Setup:** Current = target = 45°
|
||||
- **Action:** Call `turnTo(45)`
|
||||
- **Assert:** Immediately COMPLETE
|
||||
- **Rationale:** Efficiency
|
||||
|
||||
---
|
||||
|
||||
## Integration Test Scenarios
|
||||
|
||||
### INT-01: Complete Autonomous Mission
|
||||
|
||||
**Objective:** Validate full autonomous sequence with multiple subsystems
|
||||
|
||||
**Scenario:**
|
||||
```
|
||||
1. Start 100cm from wall, heading 0°
|
||||
2. Drive forward (WallApproach)
|
||||
3. Stop at 10cm from wall
|
||||
4. Turn 90° right (TurnController)
|
||||
5. Drive forward 80cm (WallApproach)
|
||||
6. Stop at wall
|
||||
7. Turn back to 0° (TurnController)
|
||||
```
|
||||
|
||||
**Subsystems Involved:** WallApproach, TurnController
|
||||
|
||||
**Duration:** ~100ms simulated time
|
||||
|
||||
**Assertions:**
|
||||
- All phase transitions occur
|
||||
- Final heading within 2° of 0°
|
||||
- All stops occur at correct distances
|
||||
- No subsystem errors
|
||||
|
||||
**Result:** ✅ PASS
|
||||
|
||||
---
|
||||
|
||||
### INT-02: Sensor Failure Recovery
|
||||
|
||||
**Objective:** Validate graceful handling of sensor failures
|
||||
|
||||
**Scenario:**
|
||||
```
|
||||
1. Begin wall approach
|
||||
2. Midway, distance sensor fails
|
||||
3. System detects failure
|
||||
4. Emergency stops
|
||||
5. Reports error status
|
||||
```
|
||||
|
||||
**Fault Injection:** `sensor.simulateFailure()`
|
||||
|
||||
**Assertions:**
|
||||
- Enters ERROR state
|
||||
- Motors stop immediately
|
||||
- Error flag set
|
||||
- No crashes or exceptions
|
||||
|
||||
**Result:** ✅ PASS
|
||||
|
||||
---
|
||||
|
||||
### INT-03: Unexpected Obstacle
|
||||
|
||||
**Objective:** Test emergency stop on sudden obstacle
|
||||
|
||||
**Scenario:**
|
||||
```
|
||||
1. Approaching wall at 50cm
|
||||
2. Sudden obstacle appears at 8cm
|
||||
3. Emergency stop triggered
|
||||
```
|
||||
|
||||
**Fault Injection:** Sudden distance change
|
||||
|
||||
**Assertions:**
|
||||
- Immediate transition to STOPPED
|
||||
- No collision (motors stop)
|
||||
- System remains stable
|
||||
|
||||
**Result:** ✅ PASS
|
||||
|
||||
---
|
||||
|
||||
### INT-04: Multi-Waypoint Navigation (Square Pattern)
|
||||
|
||||
**Objective:** Validate repeated subsystem usage
|
||||
|
||||
**Scenario:**
|
||||
```
|
||||
For each side of square (4 times):
|
||||
1. Drive forward 50cm
|
||||
2. Turn 90° right
|
||||
Result: Complete square, return to start
|
||||
```
|
||||
|
||||
**Subsystems Involved:** WallApproach, TurnController (8 activations each)
|
||||
|
||||
**Assertions:**
|
||||
- All 4 sides complete
|
||||
- Final heading = 0° (back to start)
|
||||
- No accumulated errors
|
||||
- Consistent behavior each iteration
|
||||
|
||||
**Result:** ✅ PASS
|
||||
|
||||
---
|
||||
|
||||
### INT-05: Concurrent Sensor Updates
|
||||
|
||||
**Objective:** Test system with asynchronous sensor data
|
||||
|
||||
**Scenario:**
|
||||
```
|
||||
Distance sensor: Updates every cycle
|
||||
Gyro sensor: Updates every 3 cycles
|
||||
100 update cycles
|
||||
```
|
||||
|
||||
**Stress Test:** Varying sensor update rates
|
||||
|
||||
**Assertions:**
|
||||
- No crashes or errors
|
||||
- System remains stable
|
||||
- Graceful handling of stale data
|
||||
|
||||
**Result:** ✅ PASS
|
||||
|
||||
---
|
||||
|
||||
## Test Execution
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
gradlew test
|
||||
|
||||
# Run specific test class
|
||||
gradlew test --tests MotorCyclerTest
|
||||
|
||||
# Run specific test method
|
||||
gradlew test --tests WallApproachTest.testSensorFailureHandling
|
||||
|
||||
# Run with verbose output
|
||||
gradlew test --info
|
||||
```
|
||||
|
||||
### Expected Results
|
||||
|
||||
```
|
||||
Total Tests: 45
|
||||
Passed: 45
|
||||
Failed: 0
|
||||
Skipped: 0
|
||||
Duration: < 2 seconds
|
||||
|
||||
Coverage:
|
||||
- MotorCycler: 100%
|
||||
- WallApproach: 100%
|
||||
- TurnController: 100%
|
||||
```
|
||||
|
||||
### Test Reports
|
||||
|
||||
After running tests, view detailed HTML reports at:
|
||||
```
|
||||
build/reports/tests/test/index.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Rationale
|
||||
|
||||
### Why This Architecture?
|
||||
|
||||
**Separation of Concerns:**
|
||||
- Robot logic is independent of hardware
|
||||
- FTC SDK isolated to thin wrappers
|
||||
- Each subsystem has single responsibility
|
||||
|
||||
**Testability:**
|
||||
- All logic testable without hardware
|
||||
- Tests run in seconds on Windows
|
||||
- 100% code coverage achievable
|
||||
|
||||
**Maintainability:**
|
||||
- Clear component boundaries
|
||||
- Easy to add new sensors/actuators
|
||||
- Students understand each layer
|
||||
|
||||
**Professional Practice:**
|
||||
- Industry-standard patterns
|
||||
- Dependency injection
|
||||
- Interface-based design
|
||||
- Test-driven development
|
||||
|
||||
### What Makes This Different from Traditional FTC?
|
||||
|
||||
| Traditional FTC | This Architecture |
|
||||
|----------------|-------------------|
|
||||
| Logic in OpMode | Logic in subsystems |
|
||||
| Direct hardware calls | Hardware abstractions |
|
||||
| No testing without robot | 100% testable |
|
||||
| Monolithic structure | Layered architecture |
|
||||
| Hard to maintain | Clear separation |
|
||||
| Students write spaghetti | Students learn design |
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Test Data
|
||||
|
||||
### Mock Sensor Capabilities
|
||||
|
||||
**MockDistanceSensor:**
|
||||
- Set exact distance values
|
||||
- Add Gaussian noise (±N cm)
|
||||
- Simulate failures
|
||||
- Simulate gradual approach
|
||||
- Reproducible (seeded random)
|
||||
|
||||
**MockGyroSensor:**
|
||||
- Set exact heading
|
||||
- Simulate rotation
|
||||
- Add drift (°/sec)
|
||||
- Simulate calibration states
|
||||
- Wraparound handling
|
||||
|
||||
**MockMotorController:**
|
||||
- Store power settings
|
||||
- Track power history
|
||||
- No actual hardware needed
|
||||
|
||||
---
|
||||
|
||||
## Document Control
|
||||
|
||||
**Approvals:**
|
||||
- Design: ✅ Complete
|
||||
- Implementation: ✅ Complete
|
||||
- Testing: ✅ All tests passing
|
||||
- Documentation: ✅ This document
|
||||
|
||||
**Change History:**
|
||||
- 2026-02-02: Initial version, all tests passing
|
||||
|
||||
**Related Documents:**
|
||||
- `README.md` - Project overview
|
||||
- `TESTING_SHOWCASE.md` - Testing philosophy
|
||||
- `SOLUTION.md` - Technical implementation
|
||||
- `ARCHITECTURE.md` - Detailed design patterns
|
||||
Reference in New Issue
Block a user