# Test Specification — OutputManager

## Acceptance Criteria Traceability

| AC ID | Acceptance Criterion | Test IDs | Coverage |
|-------|---------------------|----------|----------|
| AC-26 | Total RAM ≤6GB (OutputManager must not contribute significant memory) | PT-02 | Covered |
| AC-27 | Coexist with YOLO pipeline — recording must not block inference | IT-01, PT-01 | Covered |

Note: OutputManager has no direct performance ACs from the acceptance criteria. Its tests ensure it supports the system's recording, logging, and operator delivery requirements defined in the architecture.

---

## Integration Tests

### IT-01: log_detection Writes Valid JSON-Line

**Summary**: Verify log_detection appends a correctly formatted JSON line to the detection log file.

**Traces to**: AC-27

**Input data**:
- DetectionLogEntry: {frame_id: 1000, label: "footpath_winter", confidence: 0.72, tier: 2, centerX: 0.5, centerY: 0.3}
- Output dir: temporary test directory

**Expected result**:
- detections.jsonl file exists in output dir
- Last line is valid JSON parseable to a dict with all input fields
- Trailing newline present

**Max execution time**: 50ms

**Dependencies**: Writable filesystem

---

### IT-02: record_frame Saves JPEG to Sequential Filename

**Summary**: Verify record_frame encodes and saves frame as JPEG with correct naming.

**Traces to**: AC-27

**Input data**:
- Frame: numpy array (1080, 1920, 3), random pixel data
- frame_id: 42, level: 1

**Expected result**:
- File `42.jpg` exists in output dir `frames/` subdirectory
- File is a valid JPEG (OpenCV can re-read it)
- File size > 0 and < 500KB (reasonable JPEG of 1080p noise)

**Max execution time**: 100ms

**Dependencies**: Writable filesystem

---

### IT-03: log_health Writes Health Entry

**Summary**: Verify log_health appends a JSON line with health data.

**Traces to**: AC-27

**Input data**:
- HealthLogEntry: {timestamp: epoch, t_junction_c: 65.0, vlm_available: true, gimbal_available: true, semantic_available: true}

**Expected result**:
- health.jsonl file exists
- Last line contains all input fields as valid JSON

**Max execution time**: 50ms

**Dependencies**: Writable filesystem

---

### IT-04: log_gimbal_command Appends to Gimbal Log

**Summary**: Verify gimbal command strings are appended to the gimbal log file.

**Traces to**: AC-27

**Input data**:
- cmd_str: "SET_ANGLES pan=10.0 tilt=-20.0 zoom=5.0"

**Expected result**:
- gimbal.log file exists
- Last line matches the input command string

**Max execution time**: 50ms

**Dependencies**: Writable filesystem

---

### IT-05: report_to_operator Formats Detection in YOLO Schema

**Summary**: Verify operator delivery formats detections with centerX, centerY, width, height, classNum, label, confidence.

**Traces to**: AC-27

**Input data**:
- list of 3 Detection objects

**Expected result**:
- Output matches existing YOLO output format (same field names, same coordinate normalization)
- All 3 detections present in output

**Max execution time**: 50ms

**Dependencies**: None

---

### IT-06: get_storage_status Returns Correct NVMe Stats

**Summary**: Verify storage status reports accurate free space percentage.

**Traces to**: AC-26

**Input data**:
- Output dir on test filesystem

**Expected result**:
- StorageStatus: nvme_free_pct in [0, 100], frames_recorded ≥ 0, detections_logged ≥ 0
- should_reduce_recording matches threshold logic (true if free < 20%)

**Max execution time**: 50ms

**Dependencies**: Writable filesystem

---

### IT-07: Circular Buffer Triggers on Low Storage

**Summary**: Verify should_reduce_recording becomes true when free space drops below 20%.

**Traces to**: AC-26

**Input data**:
- Mock statvfs to report 15% free space

**Expected result**:
- get_storage_status().should_reduce_recording == true
- At 25% free → should_reduce_recording == false

**Max execution time**: 50ms

**Dependencies**: Mock filesystem stats

---

### IT-08: Init Creates Output Directory Structure

**Summary**: Verify init() creates the expected directory structure.

**Traces to**: AC-27

**Input data**:
- output_dir: temporary path that does not exist yet

**Expected result**:
- Directory created with subdirectories for frames
- No errors

**Max execution time**: 100ms

**Dependencies**: Writable filesystem

---

### IT-09: WriteError Does Not Block Caller

**Summary**: Verify that a disk write failure (e.g., permission denied) is caught and does not propagate as an unhandled exception.

**Traces to**: AC-27

**Input data**:
- Output dir set to a read-only path

**Expected result**:
- log_detection raises no unhandled exception (catches WriteError internally)
- Error counter incremented
- Function returns normally

**Max execution time**: 50ms

**Dependencies**: Read-only filesystem path

---

## Performance Tests

### PT-01: Frame Recording Throughput at L2 Rate

**Summary**: Verify OutputManager can sustain 30 FPS frame recording without becoming a bottleneck.

**Traces to**: AC-27

**Load scenario**:
- 30 frames/second, 1080p JPEG encoding + write
- Duration: 10 seconds (300 frames)
- Ramp-up: immediate

**Expected results**:

| Metric | Target | Failure Threshold |
|--------|--------|-------------------|
| Sustained write rate | ≥30 FPS | <25 FPS |
| Encoding latency (p95) | ≤20ms | >33ms |
| Dropped frames | 0 | >5 |
| Write throughput | ≥3 MB/s | <2 MB/s |

**Resource limits**:
- CPU: ≤20% (JPEG encoding)
- Memory: ≤100MB (buffer)

---

### PT-02: Memory Usage Under Sustained Load

**Summary**: Verify no memory leak during continuous logging and recording.

**Traces to**: AC-26

**Load scenario**:
- 1000 log_detection calls + 300 record_frame calls
- Duration: 60 seconds
- Measure RSS before and after

**Expected results**:

| Metric | Target | Failure Threshold |
|--------|--------|-------------------|
| Memory growth | ≤10MB | >50MB |
| Memory leak rate | 0 MB/min | >5 MB/min |

**Resource limits**:
- Memory: ≤100MB total for OutputManager

---

## Security Tests

### ST-01: Detection Log Does Not Contain Raw Image Data

**Summary**: Verify detection JSON lines contain metadata only, not embedded image data.

**Traces to**: AC-27

**Attack vector**: Information leakage through oversized log entries

**Test procedure**:
1. Log 10 detections
2. Read detections.jsonl
3. Verify no field contains base64, raw bytes, or binary data

**Expected behavior**: Each JSON line is < 1KB; only text/numeric fields.

**Pass criteria**: All lines < 1KB, no binary data patterns.

**Fail criteria**: Any line contains embedded image data or exceeds 10KB.

---

### ST-02: Path Traversal Prevention in Output Directory

**Summary**: Verify frame_id or other inputs cannot cause writes outside the output directory.

**Traces to**: AC-27

**Attack vector**: Path traversal via crafted frame_id

**Test procedure**:
1. Call record_frame with frame_id containing "../" characters (e.g., as uint64 this shouldn't be possible, but verify string conversion)
2. Verify file is written inside output_dir only

**Expected behavior**: File written within output_dir; no file created outside.

**Pass criteria**: All files within output_dir subtree.

**Fail criteria**: File created outside output_dir.

---

## Acceptance Tests

### AT-01: Full Flight Recording Session

**Summary**: Verify OutputManager correctly handles a simulated 5-minute flight with mixed L1 and L2 recording.

**Traces to**: AC-27

**Preconditions**:
- Temporary output directory with sufficient space
- Config: recording_l1_fps=2, recording_l2_fps=30

**Steps**:

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | init(output_dir) | Directory structure created |
| 2 | Simulate 3 min L1: record_frame at 2 FPS | 360 frames written |
| 3 | Simulate 1 min L2: record_frame at 30 FPS | 1800 frames written |
| 4 | Log 50 detections during L2 | detections.jsonl has 50 lines |
| 5 | get_storage_status() | frames_recorded=2160, detections_logged=50 |

---

### AT-02: Storage Reduction Under Pressure

**Summary**: Verify the storage management signals reduce recording at the right thresholds.

**Traces to**: AC-26

**Preconditions**:
- Mock filesystem with configurable free space

**Steps**:

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | Set free space to 25% | should_reduce_recording = false |
| 2 | Set free space to 15% | should_reduce_recording = true |
| 3 | Set free space to 8% | should_reduce_recording = true (critical) |

---

## Test Data Management

**Required test data**:

| Data Set | Description | Source | Size |
|----------|-------------|--------|------|
| sample_frames | 10 sample 1080p frames for recording tests | Generated (random or real) | ~10 MB |
| sample_detections | 50 DetectionLogEntry dicts | Generated fixtures | ~5 KB |
| sample_health | 10 HealthLogEntry dicts | Generated fixtures | ~2 KB |

**Setup procedure**:
1. Create temporary output directory
2. Call init(output_dir)

**Teardown procedure**:
1. Delete temporary output directory and all contents

**Data isolation strategy**: Each test uses its own temporary directory. No shared output paths between tests.