124 lines
9.9 KiB
Markdown
124 lines
9.9 KiB
Markdown
# 自动化测试
|
||
|
||
统一入口为 `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 真机、签名/打包及真实公网测试继续使用原有专项流程,不属于默认自动化回归。
|