Files
MeshPort/docs/automated-testing.md

124 lines
9.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 自动化测试
统一入口为 `python3 scripts/test.py`,仅使用 Python 标准库。可以从任意目录运行脚本。原有单项脚本继续可用。
## 日常运行
```sh
python3 scripts/test.py
python3 scripts/test.py --list
python3 scripts/test.py sdk engine
python3 scripts/test.py client
python3 scripts/test.py client --native
python3 scripts/test.py runner
python3 scripts/test.py speed --min-mbps 10
python3 scripts/test.py combined
```
无参数等价于 `all`,覆盖自动化入口自身、Rust workspace、Go race/vet、Go → SDK TCP/UDP 联调、Flutter analyze/全量测试,以及 macOS 配置存储测试。`all` 不包含手动吞吐诊断或速度矩阵。各模块按固定顺序串行运行,不并行争用网络夹具或编译输出。
| 模块 | 范围 | 依赖 |
|---|---|---|
| `runner` | 入口脚本的失败传播、依赖跳过、超时与报告测试 | Python 3.9+ |
| `sdk` | `cargo test --workspace --release --locked`,保留显式忽略的测试 | Rust ≥1.95、protoc |
| `engine` | Go `test -race`、`vet`、构建测试引擎、显式运行真实 Go/SDK 桥接测试 | Go、C 编译器、Python、Rust/protoc |
| `client` | Flutter 依赖解析、analyze、全量测试 | Flutter(Dart ≥3.11) |
| `macos` | `LocalProfileStore` 的 Swift 本地测试 | macOS、Xcode command-line tools |
| `throughput` | 生产 TCP 封装的 channel/UDP 对照、加密 SDK 延迟吞吐诊断 | Rust/protoc |
| `speed` | 多延迟、多轮双向测速,包含 SDK、SOCKS、sing-box,自动汇总与门槛检查 | Rust/protoc、Go、C 编译器 |
| `combined` | 同进程真实 Rust SDK + Go FFI,组网/代理双路负载、UDP、故障隔离和速度对照 | macOS、Rust/protoc、Go、C 编译器 |
Rust、Go 优先复用 `scripts/cargo-local.sh`、`scripts/go-local.sh` 和项目本地工具链。Flutter 使用 PATH 中的 `flutter`。依赖解析或构建可能访问依赖仓库;测试通信使用隔离测试配置与本机夹具。macOS 存储检查在其他平台显示为 SKIP;其他平台是否能通过所有 Rust/Go/Flutter 测试仍需各自验证。
## 原生 Flutter 测试
默认 `client` 清除继承的 `MESHPORT_LIBRARY`、`MESHPORT_PROXY_LIBRARY` 等变量,依赖原生库的用例按现有机制显示为跳过,不误用旧库。`--native` 显式构建 Rust FFI 和 Go 代理库,再把这次构建的路径传给 Flutter 测试。当前原生库构建脚本只支持此入口的 macOS 路径,因此其他平台使用 `--native` 会明确报错。
原生连接 widget 测试使用固定 `load_profile` 夹具:没有外部 peer、监听服务或 STUN,不继承打包的个人默认网络。它启动应用内测试引擎,不请求管理员权限、安装 TUN 或连接用户节点。
## 可选吞吐诊断
```sh
python3 scripts/test.py throughput --rtt-ms 58 --mib 8
```
`--rtt-ms` 是双向合计的附加 RTT,必须是 0–1000 的偶数;每方向加入一半延迟。`--mib` 为每个方向的数据量,范围 1–64,默认 8 MiB。
吞吐模块显式运行两个手动诊断,不使用全局 `--include-ignored`:TCP 封装分别通过保序内存通道和本机 UDP 传输,加密 SDK 路径输出合成测试包的窗口、重复序号及 UDP 会话队列满事件。不会读取真实下载链接或用户配置,也不会创建系统 VPN。会自动解析数据、检查上传/下载完整性、参数一致性和正的有限速度;绝对速度与基线门槛使用下面的 `speed` 模块。
夹具内部还有 60/90 秒的传输保护;很大的 RTT 与数据量组合可能触发该保护。入口的 `--timeout` 不覆盖夹具内部超时。
## 速度矩阵与性能门槛
```sh
python3 scripts/test.py speed --min-mbps 10
python3 scripts/test.py all speed --native --min-mbps 10
python3 scripts/test.py speed --rtts-ms 0,58,100 --repeat 3 --mib 8
```
默认在 0、58、100 ms 附加 RTT 下各运行 3 轮,每方向传输 8 MiB。包含生产 TCP 封装的内存通道/普通 UDP 对照,以及 SDK 直连、SOCKS、sing-box → SOCKS 三条加密组网路径,共 90 个方向测量样本、30 个汇总分组。单独运行 `speed` 会构建所需 Go 引擎;与 `all` 合并时复用引擎构建。与 `throughput` 同时指定时只执行覆盖更完整的速度矩阵。
每个分组记录中位数、最小/最大 Mbps、重复 TCP 数据序号、最大数据包间隔与会话队列满事件。判定规则:
- 缺少某条路径的上传/下载、缺少包级统计、速度非正/非有限、参数不一致或重复样本,即使命令返回 0 也判失败。
- 每组必须完成指定轮数,组中位数不能低于 `--min-mbps`。默认 0,表示不设置跨机器的统一绝对速度要求;上面的 10 Mbps 是显式配置的本地验收值,不是公网速度承诺。
- SDK 会话队列满事件在每组的所有轮次中合计不能超过 `--max-queue-drops`,默认 0。该门槛用于加密 SDK 路径;普通通道没有 SDK 会话队列。
- 不对所有重复序号/零窗口设置硬性零阈值,因为它们不独立等同于实际丢包;原始统计保留供诊断。
基线回归比较:
```sh
python3 scripts/test.py speed --baseline /path/to/previous/metrics.json \
--max-regression-percent 20 --min-mbps 10
```
基线应来自同一机器、可比较的负载和工具链。模式、目标、入口、RTT、每方向数据量和方向必须完全匹配,否则拒绝比较;当前组中位数下降超过指定百分比时失败。基线格式、有限数值和重复分组也会验证。矩阵/门槛参数必须与 `speed` 一起使用,避免只跑功能测试却误认为已检查速度。
这是本机合成链路回归,不覆盖系统 TUN、真实公网节点、真实 NAS 下载或网络切换。实际 App 测速功能另有 HTTP 代理夹具,覆盖 Mbps 换算、首字节时间、空响应、非法端口、重定向、并发重入、超时/部分数据、取消恢复、传输上限和禁止直连回退。
## sing-box 与组网联合测试
```sh
python3 scripts/test.py combined
python3 scripts/test.py combined --rtt-ms 58 --joint-repeat 3 --joint-seconds 2 --proxy-mbps 100
python3 scripts/test.py combined --proxy-mbps 0
```
`combined` 是显式选择的测试,不包含在默认 `all` 中。它构建 Go 共享库,在同一进程加载真实 Go FFI 和 Rust SDK,通过加密 EasyTier UDP 链路连接隔离节点。代理出口使用本地 SOCKS 上游夹具。不会启动系统 TUN、修改系统 VPN 或读取真实代理配置;因此不能据此判断真实运营商、NAS、公网代理或 TUN 路由冲突。
默认模拟组网 RTT 58 ms,每路每次持续至少 2 秒、重复 3 轮。分别对照组网路由配置、代理路由配置、联合配置单路传输、联合配置双路并发,覆盖上传和下载,共 36 个速度样本。SDK 节点在代理基线阶段保持空闲。代理夹具默认限速 100 Mbps,方便比较相同负载;`--proxy-mbps 0` 取消限速,用于主机资源竞争压力测试,可能暴露 CPU/内存带宽竞争。
双路并发要求传输重叠至少为配置时长的 80%,并在两路 TCP 同时传输期间分别完成 24 次 UDP 校验(默认三轮)。TCP/UDP 使用不同路径标记并校验数据,统计上游访问目标,检查组网流量没有进入代理出口。故障注入分别停止代理上游和组网桥接/节点,要求另一条已建立的传输继续成功;同时验证代理上游恢复以及每次停止后监听端口释放。
自动比较各方向中位数:联合配置空闲一路相对单独配置、并发相对联合配置单路、并发相对单独配置。下降超过 `--max-joint-slowdown-percent`(默认 20%)会使测试失败,测量仍保留在报告中。缺失样本、无效速度、重叠不足、UDP 或故障隔离未完成,即使命令返回 0 也会判失败。短时本地测试存在波动,不能替代长时间真实网络测试。
额外输出 `combined-metrics.json` 和 `combined-summary.md`,包含逐轮结果、中位数、变化百分比及功能检查证据。
## 报告与失败处理
默认输出目录:`outputs/validation/automated-tests/<UTC时间>-<随机ID>/`,已加入 Git 忽略规则。
- 每条命令一个 `.log`,终端输出运行阶段、耗时和失败日志末尾。
- `report.json` 记录命令、工作目录、状态、退出码、耗时和日志路径,不保存运行环境变量。
- `junit.xml` 以命令为 testcase,适合 CI 汇总;单元测试内部的通过/跳过数量在对应原始日志中。
- 速度模块另生成 `metrics.json`(逐次测量及分组汇总,可作为基线)和 `speed-summary.md`(易读表格);`speed-check` 的门槛失败同时进入 JSON/JUnit 和最终退出码。
任何失败返回 1;中断返回 130。默认继续其他独立模块,构建失败时跳过依赖它的步骤,最终仍返回失败。`--fail-fast` 在首个失败后跳过剩余步骤。每条命令默认最多运行 900 秒,超时终止命令及其进程组并记录退出码 124;可用 `--timeout 1800` 调整。
```sh
python3 scripts/test.py sdk engine --fail-fast --timeout 1800
python3 scripts/test.py all --log-dir /tmp/meshport-ci-results
```
自定义 `--log-dir` 必须尚不存在,以防覆盖历史记录。入口会清除所有继承的 `MESHPORT_*` 环境变量,再为所选模块设置必要的测试路径和参数,避免旧动态库、真实 profile 或遗留诊断开关影响本轮测试。
## CI 接入
在 CI 中安装所选模块的依赖后运行同一命令,直接使用其退出码判断成功;无论结果如何,收集报告目录中的 JSON、JUnit XML 和 `.log`。例如只验证 SDK 与引擎:
```sh
python3 scripts/test.py sdk engine --log-dir /tmp/meshport-ci-results
```
本次提供的是可供 CI 调用的测试入口,没有添加自动推送、发布或安装应用的步骤。系统 TUN、Android 真机、签名/打包及真实公网测试继续使用原有专项流程,不属于默认自动化回归。