memseek-test
基于场景的异步正确性验证与压测框架 —— 同一套
Scenario,既是接口正确性的断言用例,也是压测负载。
Scenario-based async correctness verification and load testing for Rust. One Scenario gives you both an assertion suite and a load generator.
为什么不是"又一个压测框架"
多数压测工具只回答"快不快"(RPS、p99、吞吐),而接口"对不对"通常靠另一套 e2e 测试回答。两边的用例几乎一样——同一批接口、同一份请求体、同一套准备数据——却要写两遍。
memseek-test 把两件事合并到同一个场景里:
RunMode::Times(n)—— 跑固定轮次,把每个Scenario当正确性断言执行,失败率/超时率超标即 CI 退出码非 0;RunMode::Duration(d)—— 跑固定时长,同一份场景直接当压测用,输出 HDR 直方图延迟分位。
Scenario 的 run 负责发请求,validate 负责断言 —— 断言不只看状态码,还可以拿响应和数据库 / Redis / 对象存储对账(这正是它在真实后端 e2e 里的用法)。
核心能力
- 正确性断言是一等公民:
validate阶段独立统计(validate_success/validate_failures),断言失败与请求失败分开计数。 - 五段生命周期:
setup→run→validate→teardown→reconcile,后三段可省略;setup/teardown支持按任务或按轮执行,reconcile每场景执行一次。 - teardown 是 finally 语义: 无论
run成功失败都会执行,且失败被单列(teardown_failures),不会污染通过率。 - 全局对账 (
reconcile): 所有并发任务结束后执行一次,用于校验计数与明细一致、无重复行等单轮断言看不到的聚合不变量;失败单列invariant_failures,不影响单轮通过率。 - 状态码统计:
ScenarioError::status_code()可选提供 HTTP 状态码,报告按 4xx/5xx 聚合,便于区分「预期业务失败」与「真实故障」。 - 对账友好: 场景上下文是任意
Send + Sync类型,可挂载数据库连接池、Redis、S3 客户端,断言时直接查库比对。 - HDR 直方图报告:
min/avg/p50/p95/p99/ RPS,按场景输出,内建 ANSI 柱状图渲染。 - 优雅关闭: Ctrl-C 或程序化触发,正在跑的请求正常收尾并计入统计,报告标注
interrupted。 - 超时退避: 超时视为过载信号,指数退避降低施压速率,过载时可关闭。
- 多线程分片:
with_workers(n)把并发任务切成 n 个分片跑在独立 OS 线程上。 - 可选全屏 TUI: 实时进度条 + 日志滚动区,业务
tracing日志可直接接入日志区。 - HTTP 辅助: 基于
reqwest的客户端封装,带默认超时、响应体快照、错误分类。
安装
[]
= "0.26"
= { = "1", = ["rt-multi-thread", "macros"] }
# 需要全屏 TUI 时:
# memseek-test = { version = "0.26", features = ["tui"] }
需要 Rust 1.88+(edition 2024;此下界由 hdrhistogram 与 url→idna→icu 依赖链决定),并且请使用多线程 tokio 运行时——TUI 渲染与 Ctrl-C 监听都是在后台 spawn 出来的,current_thread 运行时下它们会被饿死(框架检测到会给出警告)。
0.26 迁移:
Scenario::setup改为必填,Setup不再要求Default。 无前置准备时补一个async fn setup(...) -> Result<(), _> { Ok(()) }即可; 这样不再依赖「忘记写 setup 时静默使用默认值」的隐式行为。
五分钟上手
use ;
/// 全局上下文: 被测地址 + 复用的 HTTP 客户端(连接池共享)
/// 健康检查: 期待 200, 且响应体含 "ok"
;
register_scenario!;
async
register_scenario! 在编译期链接期登记场景(基于 inventory),run_all 只会运行 Ctx 类型匹配的场景。想改名或指定默认模式:
register_scenario!;
可运行示例
examples/ 下每个示例对应上面一个主题,都能直接跑:
| 示例 | 跑法 | 演示什么 |
|---|---|---|
quickstart |
cargo run --example quickstart |
Times 模式 + validate 对账 + CI 判定,不需要任何外部服务 |
http |
cargo run --example http |
Client、请求构造、send_checked、错误分类(需先起一个本地 HTTP 服务) |
graceful_shutdown |
cargo run --example graceful_shutdown |
程序化优雅停止、按名执行单个场景、report.interrupted |
per_round_setup |
cargo run --example per_round_setup |
按轮的 setup/teardown、finally 语义、teardown_failures 单列 |
tui |
cargo run --example tui --features tui |
全屏进度与日志滚动区接线 |
真实用法: 后端 e2e 正确性套件
下面摘自一个真实 Rust 后端项目的 e2e 套件(63 个场景:auth 8 / user 22 / visual 32 / system 1)——它的主用途就是上线前的正确性验收:run 打接口,validate 拿响应和数据库逐字段对账。
1. 上下文里挂上"对账用的眼"
2. setup 里登录拿会话(每个并发任务一次)
/// 会话预置: 每个并发任务用自己池子里的账号登录, 凭证随任务走
;
register_scenario!;
负例场景同样只是断言,不需要额外机制:
/// 未携带认证头: 期望 401
async
3. 按轮的 setup / teardown 做资源清理
写场景每轮都要新的输入、并要清掉本轮产物:
use json;
register_scenario!;
4. 按白名单/黑名单挑场景,汇总判定给 CI
let all = ;
let selected: = all
.into_iter
.filter
.filter
.collect;
let reports = manager.run.await;
println!;
let times: u64 = reports.iter.map.sum;
let failures: u64 = reports.iter.map.sum;
let timeouts: u64 = reports.iter.map.sum;
let interrupted = reports.iter.any;
if times == 0 || failures > 0 || timeouts > 0 || interrupted
名单里写错场景名要直接退出报错,别让它退化成"静默少跑"。
生命周期语义
setup ──► run ──► validate ──► teardown ──► reconcile
(每场景一次,所有任务结束后)
| 阶段 | 何时跑 | 失败如何记账 |
|---|---|---|
setup |
按任务(默认)或按轮 | 判一轮失败;若为超时则触发退避重试 |
run |
必填,每轮一次 | 记 failures 或 timeouts,并跳过 validate |
validate |
仅当 run 成功 |
Ok(false) 记为 validate 分类;Err 按 Error::kind() 分类;两者都计入 validate_failures |
teardown |
finally,退出前必跑 | 只影响 teardown_failures + teardown:{kind},不影响通过率、不触发退避 |
reconcile |
所有并发任务结束后一次 | 只进 invariant_failures;不影响单轮通过率,耗时单列 reconcile_total |
setup / teardown 的耗时不计入延迟分位(它们不属于 run),但会拖慢轮次节奏,因此报告的 RPS 反映的是含准备与收尾的整体吞吐。
全局对账 (reconcile)
单轮 validate 只能看到「这次请求自己的结果」;高并发下的计数漂移、重复行、缓存与库不一致需要所有任务结束后再对一次账:
async
- 返回空
Vec= 通过;每条 violation 带稳定的name与可定位的detail。 - 返回
Err会折叠为reconcile:{kind},不会静默跳过。 - 失败不计入
failures/validate_failures;调用方应把invariant_failures作为独立判定条件。 - 被 SIGINT 中断但已启动的场景仍会执行;因关闭信号未启动的场景不执行。
错误分类
实现 ScenarioError 即可自定义分类;框架内建的 HttpError 已按下列类别归类,直接体现在报告的 error_map 里。另可实现 status_code() 让报告额外聚合 4xx/5xx:
http_status_404 timeout connect_refused connect_dns connect_unreachable serialize decode ...
对未包装的原生 reqwest 请求,框架同样为 reqwest::Error 实现了 ScenarioError,归类方式一致。
报告里的 Status: 4xx x | 5xx y 来自 ScenarioError::status_code()(默认 None)。负向用例把预期 4xx 归一为 Ok(code) 时不会计入,因此 4xx/5xx 反映的是意外错误。
运行模式与执行控制
new // 并发度(0 会 panic)
.with_run_mode
.with_workers // 切成 4 个分片跑在独立 OS 线程
.with_backoff
.with_shutdown // 程序化触发优雅停止
.install_ctrl_c // 或直接监听 SIGINT
RunMode::Times(n)—— 正确性验收。n是所有并发任务之和的总轮次。RunMode::Duration(d)—— 压测。到点停止,正在跑的请求收尾后计入统计。with_workers(n)—— 分片并行。task.index/task.total仍全局一致,报告口径不受影响;n会被夹到并发度以内。- 退避 —— 只在超时时触发;压测场景建议显式关闭,否则过载时框架会自动减速,压不出目标速率。
程序化停止:
let = new;
spawn;
报告
println!; // 纯文本块
println!;
println!; // 快捷方式
Report 已为单条 ScenarioReport、&[ScenarioReport] 和 Vec<ScenarioReport> 实现,所以 reports.report() 直接可用。
ScenarioReport 里对判定最有用的字段:times、success、failures、validate_success、validate_failures、timeouts、teardown_failures、error_map、status_counts、invariant_failures、interrupted,以及 p50 / p95 / p99 / avg / min / max 与各阶段耗时(含 reconcile_total)。
HTTP 辅助
use ;
// 默认 3s 超时; 需要完整控制(连接池/TLS/代理)时用 from_reqwest
let client = new?;
// 或: Client::from_reqwest(reqwest::Client::builder().timeout(...).build()?, base)?;
let resp = client
.request
.header
.query
.json? // 序列化失败返回 Err
.send_checked // 非 2xx -> HttpError::Status, 并保留请求/响应体快照
.await?;
// 高 QPS 下关掉响应体快照, 省内存
let client = client.with_capture;
send()不做状态码校验;send_checked()把非 2xx 变成错误,并带上请求/响应体快照,失败时能在报告里看到现场。- 相对路径会保留
base_url的路径前缀(.../api+/auth→.../api/auth)。 Client实现了Deref<Target = reqwest::Client>,原生 reqwest API 随时可用;reqwest与reqwest::multipart已从本 crate 重导出,保证版本一致。
TUI(feature = tui)
let channel = with_capacity;
fmt
.with_writer // 业务日志直接进 TUI 日志区
.init;
// 调整显示参数; 全部用默认值时直接 TuiOptions::default().with_channel(channel)
let mut options = default;
options.log_lines = 12; // 日志区行数
options.refresh = from_millis; // 刷新间隔
options.bar_width = 40; // 进度条宽度
options.color = true;
let manager = new;
全屏显示顶部实时进度 + 日志滚动区;退出后日志缓冲回放到 stderr。非 TTY(重定向 / CI)会自动静默。终端行数不足时进度行会被顶出可视区,调小 log_lines 即可。
功能开关
| feature | 默认 | 说明 |
|---|---|---|
tui |
否 | 全屏进度 TUI、LogChannel、TuiOptions |
写在最后
validate 里的断言就是普通的 Rust 代码 —— 能查数据库、能读 Redis、能比对对象存储,不必迁就任何 DSL。压测与正确性验证共用一个场景,是这个小框架唯一想坚持的事。
License
MIT