# Test Specification — GimbalDriver

## Acceptance Criteria Traceability

| AC ID | Acceptance Criterion | Test IDs | Coverage |
|-------|---------------------|----------|----------|
| AC-16 | Gimbal control sends pan/tilt/zoom commands to ViewPro A40 | IT-01, IT-02, AT-01 | Covered |
| AC-17 | Gimbal command latency ≤500ms from decision to physical movement | PT-01 | Covered |
| AC-18 | Zoom transitions: medium to high zoom within 2 seconds | IT-05, PT-02, AT-02 | Covered |
| AC-19 | Path-following accuracy: footpath stays within center 50% of frame | IT-06, AT-03 | Covered |
| AC-20 | Smooth gimbal transitions (no jerky movements) | IT-07, PT-03 | Covered |

---

## Integration Tests

### IT-01: Connect to UART (Mock TCP Mode)

**Summary**: Verify GimbalDriver connects to mock-gimbal service via TCP socket in dev mode.

**Traces to**: AC-16

**Input data**:
- Config: gimbal.mode=mock_tcp, mock_host=localhost, mock_port=9090
- Mock gimbal TCP server running

**Expected result**:
- connect() returns true
- is_alive() returns true
- get_state() returns GimbalState with valid initial values

**Max execution time**: 2s

**Dependencies**: Mock gimbal TCP server

---

### IT-02: set_angles Sends Correct ViewLink Command

**Summary**: Verify set_angles translates pan/tilt/zoom to a valid ViewLink serial packet.

**Traces to**: AC-16

**Input data**:
- Mock server that captures raw bytes received
- set_angles(pan=15.0, tilt=-30.0, zoom=20.0)

**Expected result**:
- Byte packet matches ViewLink protocol format (header, payload, checksum)
- Mock server acknowledges command
- set_angles returns true

**Max execution time**: 500ms

**Dependencies**: Mock gimbal server with byte capture

---

### IT-03: Connection Failure Returns False

**Summary**: Verify connect() returns false when UART/TCP port is unavailable.

**Traces to**: AC-16

**Input data**:
- Config: mock_port=9091 (no server listening)

**Expected result**:
- connect() returns false
- is_alive() returns false
- No crash or hang

**Max execution time**: 3s (with connection timeout)

**Dependencies**: None

---

### IT-04: Heartbeat Timeout Marks Gimbal Dead

**Summary**: Verify is_alive() returns false after 4 seconds without a heartbeat response.

**Traces to**: AC-16

**Input data**:
- Connected mock server that stops responding after initial connection
- Config: gimbal_timeout_s=4

**Expected result**:
- is_alive() returns true initially
- After 4s without heartbeat → is_alive() returns false

**Max execution time**: 6s

**Dependencies**: Mock gimbal server with configurable response behavior

---

### IT-05: zoom_to_poi Blocks Until Zoom Complete

**Summary**: Verify zoom_to_poi waits for zoom transition to complete before returning.

**Traces to**: AC-18

**Input data**:
- Current zoom=1.0, target zoom=20.0
- Mock server simulates 1.5s zoom transition

**Expected result**:
- zoom_to_poi blocks for ~1.5s
- Returns true after zoom completes
- get_state().zoom ≈ 20.0

**Max execution time**: 3s

**Dependencies**: Mock gimbal server with simulated zoom delay

---

### IT-06: follow_path PID Updates Direction

**Summary**: Verify follow_path computes PID output and sends angular velocity commands.

**Traces to**: AC-19

**Input data**:
- direction=(0.7, 0.3)
- pid_error=50.0 (pixels offset from center)
- PID gains: P=0.5, I=0.01, D=0.1

**Expected result**:
- Pan/tilt velocity commands sent to mock server
- Command magnitude proportional to error
- Returns true

**Max execution time**: 100ms

**Dependencies**: Mock gimbal server

---

### IT-07: PID Anti-Windup Clamps Integral

**Summary**: Verify the PID integral term does not wind up during sustained error.

**Traces to**: AC-20

**Input data**:
- 100 consecutive follow_path calls with constant pid_error=200.0
- PID integral clamp configured

**Expected result**:
- Integral term stabilizes at clamp value (does not grow unbounded)
- Command output reaches a plateau, no overshoot oscillation

**Max execution time**: 500ms

**Dependencies**: Mock gimbal server

---

### IT-08: Retry on Checksum Failure

**Summary**: Verify the driver retries up to 3 times when a checksum mismatch is detected.

**Traces to**: AC-16

**Input data**:
- Mock server returns corrupted response (bad checksum) on first 2 attempts, valid on 3rd

**Expected result**:
- set_angles retries 2 times, succeeds on 3rd
- Returns true
- If all 3 fail, raises GimbalCommandError

**Max execution time**: 500ms

**Dependencies**: Mock gimbal server with configurable corruption

---

### IT-09: return_to_sweep Resets Zoom to Medium

**Summary**: Verify return_to_sweep zooms out to medium zoom level and resumes sweep angle.

**Traces to**: AC-16

**Input data**:
- Current state: zoom=20.0, pan=15.0
- Expected return: zoom=1.0 (medium)

**Expected result**:
- Zoom command sent to return to medium zoom
- Returns true after zoom transition completes

**Max execution time**: 3s

**Dependencies**: Mock gimbal server

---

## Performance Tests

### PT-01: Command-to-Acknowledgement Latency

**Summary**: Measure round-trip time from set_angles call to server acknowledgement.

**Traces to**: AC-17

**Load scenario**:
- 100 sequential set_angles commands
- Mock server with 10ms simulated processing
- Duration: ~15s

**Expected results**:

| Metric | Target | Failure Threshold |
|--------|--------|-------------------|
| Latency (p50) | ≤50ms | >500ms |
| Latency (p95) | ≤200ms | >500ms |
| Latency (p99) | ≤400ms | >500ms |

**Resource limits**:
- CPU: ≤10%
- Memory: ≤50MB

---

### PT-02: Zoom Transition Duration

**Summary**: Measure time from zoom command to zoom-complete acknowledgement.

**Traces to**: AC-18

**Load scenario**:
- 10 zoom transitions: alternating 1x→20x and 20x→1x
- Mock server with realistic zoom delay (1-2s)
- Duration: ~30s

**Expected results**:

| Metric | Target | Failure Threshold |
|--------|--------|-------------------|
| Transition time (p50) | ≤1.5s | >2.0s |
| Transition time (p95) | ≤2.0s | >2.5s |

**Resource limits**:
- CPU: ≤5%

---

### PT-03: PID Follow Smoothness (Jerk Metric)

**Summary**: Measure gimbal command smoothness during path following by computing jerk (rate of acceleration change).

**Traces to**: AC-20

**Load scenario**:
- 200 PID updates at 10Hz (20s follow)
- Path with gentle curve (sinusoidal trajectory)
- Mock server records all received angular velocity commands

**Expected results**:

| Metric | Target | Failure Threshold |
|--------|--------|-------------------|
| Max jerk (deg/s³) | ≤50 | >200 |
| Mean jerk (deg/s³) | ≤10 | >50 |

**Resource limits**:
- CPU: ≤15% (PID computation)

---

## Security Tests

### ST-01: UART Buffer Overflow Protection

**Summary**: Verify the driver handles oversized responses without buffer overflow.

**Traces to**: AC-16

**Attack vector**: Malformed or oversized serial response (EMI corruption, spoofing)

**Test procedure**:
1. Mock server sends response exceeding max expected packet size (e.g., 10KB)
2. Mock server sends response with invalid header bytes

**Expected behavior**: Driver discards oversized/malformed packets, logs warning, continues operation.

**Pass criteria**: No crash, no memory corruption; is_alive() still returns true after discarding bad packet.

**Fail criteria**: Buffer overflow, crash, or undefined behavior.

---

## Acceptance Tests

### AT-01: Pan/Tilt/Zoom Control End-to-End

**Summary**: Verify the full command cycle: set angles, read back state, verify match.

**Traces to**: AC-16

**Preconditions**:
- GimbalDriver connected to mock server

**Steps**:

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | set_angles(pan=10, tilt=-20, zoom=5) | Returns true |
| 2 | get_state() | pan≈10, tilt≈-20, zoom≈5 (within tolerance) |
| 3 | set_angles(pan=-30, tilt=0, zoom=1) | Returns true |
| 4 | get_state() | pan≈-30, tilt≈0, zoom≈1 |

---

### AT-02: Zoom Transition Timing Compliance

**Summary**: Verify zoom from medium to high completes within 2 seconds.

**Traces to**: AC-18

**Preconditions**:
- GimbalDriver connected, current zoom=1.0

**Steps**:

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | Record timestamp T0 | — |
| 2 | zoom_to_poi(pan=0, tilt=-10, zoom=20) | Blocks until complete |
| 3 | Record timestamp T1 | T1 - T0 ≤ 2.0s |
| 4 | get_state().zoom | ≈ 20.0 |

---

### AT-03: Path Following Keeps Error Within Bounds

**Summary**: Verify PID controller keeps path tracking error within center 50% of frame.

**Traces to**: AC-19

**Preconditions**:
- Mock server simulates gimbal with realistic response dynamics
- Trajectory: 20 waypoints along a curved path

**Steps**:

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | Start follow_path with trajectory | PID commands issued |
| 2 | Simulate 100 PID cycles at 10Hz | Commands recorded by mock |
| 3 | Compute simulated frame-center error | Error < 50% of frame width for ≥90% of cycles |

---

## Test Data Management

**Required test data**:

| Data Set | Description | Source | Size |
|----------|-------------|--------|------|
| viewlink_packets | Reference ViewLink protocol packets for validation | Captured from spec / ArduPilot | ~10 KB |
| pid_trajectories | Sinusoidal and curved path trajectories for PID testing | Generated | ~5 KB |
| corrupted_responses | Oversized and malformed serial response bytes | Generated | ~1 KB |

**Setup procedure**:
1. Start mock-gimbal TCP server on configured port
2. Initialize GimbalDriver with mock_tcp config
3. Call connect()

**Teardown procedure**:
1. Call disconnect()
2. Stop mock-gimbal server

**Data isolation strategy**: Each test uses its own GimbalDriver instance connected to a fresh mock server. No shared state.