xtkuang
428ee328de
Vendor MsQuic with build and install support, add DeviceManager status to configurable heartbeats, and report only enabled devices. Add the local QUIC gateway, protocol coverage, real MsQuic E2E tests, process smoke tests, and updated integration documentation.
123 lines
4.9 KiB
Markdown
123 lines
4.9 KiB
Markdown
# 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，不得用于生产环境。
|