Files
MeshPort/docs/automated-testing.md

9.9 KiB
Raw Permalink Blame History

自动化测试

统一入口为 python3 scripts/test.py,仅使用 Python 标准库。可以从任意目录运行脚本。原有单项脚本继续可用。

日常运行

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 或连接用户节点。

可选吞吐诊断

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 不覆盖夹具内部超时。

速度矩阵与性能门槛

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 会话队列。
  • 不对所有重复序号/零窗口设置硬性零阈值,因为它们不独立等同于实际丢包;原始统计保留供诊断。

基线回归比较:

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 与组网联合测试

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 调整。

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 与引擎:

python3 scripts/test.py sdk engine --log-dir /tmp/meshport-ci-results

本次提供的是可供 CI 调用的测试入口,没有添加自动推送、发布或安装应用的步骤。系统 TUN、Android 真机、签名/打包及真实公网测试继续使用原有专项流程,不属于默认自动化回归。