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