# QUIC 真实端到端测试

本目录验证生产 QUIC client 代码与
[`test/quic_gateway/`](../quic_gateway/) 中真实 MsQuic Server 的互操作，不使用
fake transport，也不要求连接物理设备。

## 测试矩阵

| CTest 名称 | 进程边界 | 覆盖内容 |
| --- | --- | --- |
| `cmvr_quic_msquic_e2e_test` | 测试进程内同时运行 Gateway 和生产 `QuicEdgeService` | TLS/ALPN、注册、DeviceManager 合成快照、至少两次心跳 ACK、H.264/AAC descriptor 精确字段、真实 DATAGRAM、分片、序列号、flags、长度与载荷哈希 |
| `cmvr_es_quic_process_smoke_test` | 分别启动测试 Gateway 和真实 `cmvr_es` 子进程 | 临时配置加载、`QuicEdgeTask` 工厂和生命周期、节点注册、IP、禁用设备过滤、已启用设备创建失败上报、本地心跳周期、至少两次心跳 ACK、SIGTERM 安全退出 |

第一项向生产 `MediaSourceHub` 注册两个有界 synthetic source：

- 2500 字节的 H.264 Annex B IDR 视频帧，用于覆盖 DATAGRAM 分片；
- 带 ADTS header 的 AAC-LC 48 kHz 双声道音频帧。

测试先发送 discovery 帧触发可靠 descriptor，确认 Gateway 已安装两个轨道后，
再发送 priming 和 validation 帧，因此不会把 reliable stream 与 DATAGRAM 的
跨通道乱序误报成失败。最终 validation 帧按轨道精确校验 sequence、字节数、
flags 和 FNV-1a 载荷哈希。

它验证的是媒体传输和协议封装，不验证摄像头、麦克风或编码器驱动。第二项生成
一棵临时 Proto Text 配置树，配置两个禁用设备和一个无配置文件的已启用设备，
只启用 QUIC 任务；它会验证禁用设备不会出现在 heartbeat 中、已启用设备的创建
失败仍会作为异常行上报，并让 Gateway 返回零周期以保留边缘配置；
测试结束后临时
目录自动清理，不会修改 `cmvr-es/config/`、`output/bin/config/` 或
`output/bin/model/`。

## 构建并运行

先按根目录 README 构建固定版本的仓库内 MsQuic：

```bash
script/build_msquic.sh \
  --arch x86 \
  --version 2.5.9 \
  --jobs "$(nproc)" \
  --clean
```

再配置真实后端和测试：

```bash
cmake -S . -B build-quic \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMVR_ARCH=x86 \
  -DCMVR_ENABLE_MSQUIC_BACKEND=ON \
  -DCMVR_REQUIRE_MSQUIC=ON \
  -DCMVR_ALLOW_SYSTEM_MSQUIC=OFF \
  -DCMVR_MSQUIC_VERSION=2.5.9 \
  -DBUILD_TESTING=ON \
  -DCMVR_BUILD_QUIC_TEST_GATEWAY=ON \
  -DCMVR_INSTALL_DEFAULT_RUNTIME_ASSETS=OFF

cmake --build build-quic -j"$(nproc)"
ctest \
  --test-dir build-quic \
  --output-on-failure \
  -R 'cmvr_quic_msquic_e2e_test|cmvr_es_quic_process_smoke_test'
```

要求：

- `dependency/x86/third_party/msquic/v2.5.9` 已完整生成；
- 本机可执行 `openssl`，CMake 用它在
  `build-quic/test/certs/` 生成 7 天有效的 loopback 证书；
- 完整进程冒烟需要 Python 3.10 或更高版本；
- 运行环境允许在 `127.0.0.1` 创建 UDP listener 和 QUIC 连接。

测试被标记为 `RUN_SERIAL`，避免端口、证书和进程日志互相干扰。也可按 label
运行：

```bash
ctest --test-dir build-quic --output-on-failure -L 'quic|e2e'
```

CTest 会为构建树补齐仓库内共享库搜索路径。人工启动 Gateway 时应使用 CMake
生成的
`build-quic/test/quic_gateway/run_cmvr_quic_test_gateway` 包装器，而不是直接
执行裸二进制；参数和 summary 字段见
[`test/quic_gateway/README.md`](../quic_gateway/README.md)。

## 通过条件

真实媒体 E2E 至少要求：

- 一次注册被接受，且至少两个心跳被精确 ACK；
- 一个媒体 session 和两个轨道描述到达，且 codec、payload format、分辨率或
  采样参数、generation 和 codec config 与源描述完全一致；
- 视频和音频 validation 帧均完成重组，最大 sequence、track ID、长度、flags
  和载荷哈希与发送值完全一致；
- Edge 与 Gateway 的 session ID 一致；
- `protocol_violations == 0`，两端均无运行时错误；
- client、连接、listener 和后台队列能够有序停止。

完整进程冒烟至少要求：

- `cmvr_es` 日志出现 `[QuicEdgeTask] Started`；
- 没有使用不可用占位后端；
- Gateway 接受 `cmvr-process-smoke` 节点注册；
- 收到并回复至少两个心跳；
- 心跳中的 Manager 元数据正确，两个禁用设备均未上报，已启用设备的创建失败
  以 `ERROR` 行上报；
- Gateway 和 `cmvr_es` 都以退出码 0 结束。

失败时进程冒烟会输出 Gateway 与 `cmvr_es` 的完整临时日志，便于区分依赖加载、
UDP 监听、TLS、协议或生命周期问题。

## 不覆盖的能力

这些测试不替代：

- 真机摄像头、麦克风和厂商 SDK 验证；
- 真实编码器码流质量和长时间压力测试；
- 丢包、抖动、NAT、防火墙和弱网测试；
- Java 生产 Gateway、鉴权、状态持久化和浏览器转发；
- mTLS、生产 CA、业务 token 或设备 ACL。

测试证书和 `allow_insecure` 只用于本机 loopback，不得用于生产环境。