Initial commit

Made-with: Cursor

_docs/02_plans/components/06_output_manager/tests.md

@@ -0,0 +1,346 @@
+# 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.