detections-semantic/_docs/02_plans/integration_tests/environment.md

# E2E Test Environment

## Overview

**System under test**: Semantic Detection Service — a Cython + TensorRT module running within the existing FastAPI detections service on Jetson Orin Nano Super. Entry points: FastAPI REST API (image/video input), UART serial port (gimbal commands), Unix socket (VLM IPC).

**Consumer app purpose**: Standalone Python test runner that exercises the semantic detection pipeline through its public interfaces: submitting frames, injecting mock YOLO detections, capturing detection results, and monitoring gimbal command output. No access to internals.

## Docker Environment

### Services

| Service | Image / Build | Purpose | Ports |
|---------|--------------|---------|-------|
| semantic-detection | build: ./Dockerfile.test | Main semantic detection pipeline (Tier 1 + 2 + scan controller + gimbal driver + recorder) | 8080 (API) |
| mock-yolo | build: ./tests/mock_yolo/ | Provides deterministic YOLO detection output for test frames | 8081 (API) |
| mock-gimbal | build: ./tests/mock_gimbal/ | Simulates ViewPro A40 serial interface via TCP socket (replaces UART for testing) | 9090 (TCP) |
| vlm-stub | build: ./tests/vlm_stub/ | Deterministic VLM response stub via Unix socket | — (Unix socket) |
| e2e-consumer | build: ./tests/e2e/ | Black-box test runner (pytest) | — |

### Networks

| Network | Services | Purpose |
|---------|----------|---------|
| e2e-net | all | Isolated test network |

### Volumes

| Volume | Mounted to | Purpose |
|--------|-----------|---------|
| test-frames | semantic-detection:/data/frames, e2e-consumer:/data/frames | Shared test images (semantic01-04.png + synthetic frames) |
| test-output | semantic-detection:/data/output, e2e-consumer:/data/output | Detection logs, recorded frames, gimbal command log |

### docker-compose structure

```yaml
services:
  semantic-detection:
    build: .
    environment:
      - ENV=test
      - GIMBAL_HOST=mock-gimbal
      - GIMBAL_PORT=9090
      - VLM_SOCKET=/tmp/vlm.sock
      - YOLO_API=http://mock-yolo:8081
      - RECORD_PATH=/data/output/frames
      - LOG_PATH=/data/output/detections.jsonl
    volumes:
      - test-frames:/data/frames
      - test-output:/data/output
    depends_on:
      - mock-yolo
      - mock-gimbal
      - vlm-stub

  mock-yolo:
    build: ./tests/mock_yolo

  mock-gimbal:
    build: ./tests/mock_gimbal

  vlm-stub:
    build: ./tests/vlm_stub

  e2e-consumer:
    build: ./tests/e2e
    volumes:
      - test-frames:/data/frames
      - test-output:/data/output
    depends_on:
      - semantic-detection
```

## Consumer Application

**Tech stack**: Python 3.11, pytest, requests, struct (for gimbal protocol parsing)
**Entry point**: `pytest tests/e2e/ --junitxml=e2e-results/report.xml`

### Communication with system under test

| Interface | Protocol | Endpoint / Topic | Authentication |
|-----------|----------|-----------------|----------------|
| Frame submission | HTTP POST | http://semantic-detection:8080/api/v1/detect | None (internal network) |
| Detection results | HTTP GET | http://semantic-detection:8080/api/v1/results | None |
| Gimbal command log | File read | /data/output/gimbal_commands.log | None (shared volume) |
| Detection log | File read | /data/output/detections.jsonl | None (shared volume) |
| Recorded frames | File read | /data/output/frames/ | None (shared volume) |

### What the consumer does NOT have access to

- No direct access to TensorRT engine internals
- No access to YOLOE model weights or inference state
- No access to VLM process memory or internal prompts
- No direct UART/serial access (reads gimbal command log only)
- No access to scan controller state machine internals

## CI/CD Integration

**When to run**: On every PR to `dev` branch; nightly on `dev`
**Pipeline stage**: After unit tests pass, before merge approval
**Gate behavior**: Block merge on any FAIL
**Timeout**: 10 minutes total suite (most tests < 1s each; VLM tests up to 30s)

## Reporting

**Format**: JUnit XML + CSV summary
**Columns**: Test ID, Test Name, Execution Time (ms), Result (PASS/FAIL/SKIP), Error Message (if FAIL)
**Output path**: `./e2e-results/report.xml`, `./e2e-results/summary.csv`

## Hardware-in-the-Loop Test Track

Tests requiring actual Jetson Orin Nano Super hardware are marked with `[HIL]` in test IDs. These tests:
- Run on physical Jetson with real TensorRT engines
- Use real ViewPro A40 gimbal (or ViewPro simulator if available)
- Measure actual latency, memory, thermal, power
- Run separately from Docker-based E2E suite
- Triggered manually or on hardware CI runner (if available)