memseek-test 0.26.0

Scenario-based async load testing framework with HTTP helpers, HDR histogram latency reports and graceful shutdown
Documentation
use crate::{error::ScenarioError, invariant::InvariantViolation, runner::TaskIndex};

/// `setup()` 阶段的执行粒度。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SetupMode {
    /// 每个并发任务执行一次(默认);产出在任务内所有轮次间复用。
    /// 适合登录拿 token、预热客户端等会话级准备。
    Task,
    /// 每轮 `run` 之前执行一次;产出仅本轮有效。
    /// 适合验证码、唯一账号等一次性消耗数据。
    Round,
}

/// `teardown()` 阶段的执行粒度,与 [`SetupMode`] 同义:
/// `Task` = 每个任务在轮次循环结束后一次,`Round` = 每轮一次。
pub type TeardownMode = SetupMode;

/// 框架按 `block_on` + `join_all` 调度(默认单线程协作;
/// 可用 `ManagerConfig::with_workers` 分片到多个自建线程),不 `tokio::spawn`,
/// 因此不要求方法返回的 Future `Send`;若未来需要 spawn,
/// 应改为返回 `impl Future + Send` 的手写形态。
#[allow(async_fn_in_trait)]
pub trait Scenario: Default + Send + Sync + 'static {
    type Ctx: Send + Sync;
    type Error: ScenarioError;
    /// `run` 的成功产出(如 `reqwest::Response`),每轮 run 的局部值,
    /// 仅供本轮 `validate` 借用来做业务校验。
    /// 不需要产出数据时填 `()` 即可(此时 `run` 签名与旧版 `Result<(), Error>` 等价)。
    type Output;
    /// `setup` 产出的数据(如登录会话/预热客户端/本轮业务参数),
    /// 供 `run`/`validate` 借用。不需要时填 `()` 并在 `setup` 中返回 `Ok(())`。
    type Setup: Send + Sync;

    /// `setup` 执行粒度,默认每个任务一次(`SetupMode::Task`)。
    const SETUP_MODE: SetupMode = SetupMode::Task;

    /// `teardown` 执行粒度,默认每个任务一次(`TeardownMode::Task`)。
    ///
    /// - `Task`:每个任务在轮次循环结束后执行一次(含被优雅关闭提前结束的路径);
    /// - `Round`:每轮 `run`/`validate` 之后执行一次,能拿到本轮 `setup` 与 `run` 产出。
    ///
    /// 需要清理**每轮创建的资源**(如每轮下单后删除订单)时应设为 `Round`:
    /// 任务级收尾拿不到任何一轮的 `Output`。
    const TEARDOWN_MODE: TeardownMode = TeardownMode::Task;

    /// 场景展示名。
    ///
    /// 默认返回完整类型路径(如 `my_mod::HelloScenario`)。
    /// 注意:注册进 registry 的**匹配名**由 `register_scenario!` 生成,
    /// 默认是类型简单名(可用 `name = "..."` 覆盖),两者相互独立。
    fn name() -> &'static str {
        std::any::type_name::<Self>()
    }

    /// 预置阶段,按 [`Self::SETUP_MODE`] 决定执行频率:
    ///
    /// - `SetupMode::Task`:每个并发任务在 run 循环开始前执行**一次**,
    ///   产出注入该任务所有轮次的 `run`/`validate`;
    /// - `SetupMode::Round`:每轮 `run` 之前执行**一次**,
    ///   产出仅本轮有效。
    ///
    /// `task` 与 `run` 收到的为同一任务身份,可用 `task.index`
    /// 做账号等参数化预置(如 `login(format!("loadtest_{}", index))`)。
    /// 返回 `Err` 时该任务直接中止:记一次失败,不再继续。
    /// 本方法为**必填**:`Setup` 不再要求 `Default`,框架不再提供默认实现;
    /// 无预置数据时填 `type Setup = ()` 并返回 `Ok(())` 即可。
    async fn setup(ctx: &Self::Ctx, task: &TaskIndex) -> Result<Self::Setup, Self::Error>;

    /// 执行一次场景业务,返回本轮产出供 `validate` 校验。
    /// `setup` 为该任务/该轮预置阶段的产出,可借用。
    /// `task` 是框架分配的并发任务身份(编号/总数),可用 `task.index`
    /// 做账号等参数化(如 `format!("loadtest_{}", task.index + 1)`)。
    /// 返回 `Err` 时该轮直接记为失败,runner 不会调用 `validate`。
    async fn run(
        ctx: &Self::Ctx,
        task: &TaskIndex,
        setup: &Self::Setup,
    ) -> Result<Self::Output, Self::Error>;

    /// 对 run 的成功产出做业务校验,默认直接通过。
    /// `setup` 与 `task` 与 `run` 收到的为同一任务身份/预置产出。
    /// 返回 `Err` 同样记为一次 validate 失败。
    async fn validate(
        _ctx: &Self::Ctx,
        _task: &TaskIndex,
        _setup: &Self::Setup,
        _output: &Self::Output,
    ) -> Result<bool, Self::Error> {
        Ok(true)
    }

    /// 收尾阶段(finally 语义),默认什么都不做。
    ///
    /// 按 [`Self::TEARDOWN_MODE`] 决定执行频率;`run`/`validate` **无论成败**都会
    /// 执行(不同于只在 `run` 成功时执行的 `validate`),且不可被停止信号打断。
    ///
    /// `result` 为对应轮次 `run` 的结果:`Round` 粒度恒为 `Some(Ok/Err)`;
    /// `Task` 粒度没有单轮产出,恒为 `None`。
    ///
    /// 失败处理:返回 `Err` 记一次 teardown 失败(以 `teardown:{kind}` 进错误明细),
    /// **不**加剧 `failures`/`timeouts`、不触发退避、不影响通过率,也不中止任务
    /// (收尾失败不应中断压测)。
    ///
    /// 边界:`setup` 未成功(普通失败 / 首轮前被取消)时不执行任务级收尾;
    /// `SetupMode::Round` 且本轮 setup 失败时不执行本轮收尾。
    /// 另注:`SetupMode::Round` 搭配 `TeardownMode::Task` 时,任务级收尾拿到的是
    /// **最后一次成功 setup** 的产出(若从未成功 setup 过则不执行收尾)。
    async fn teardown(
        _ctx: &Self::Ctx,
        _task: &TaskIndex,
        _setup: &Self::Setup,
        _result: Option<Result<&Self::Output, &Self::Error>>,
    ) -> Result<(), Self::Error> {
        Ok(())
    }

    /// 全局对账阶段,默认不检查。
    ///
    /// 在所有并发任务结束(含中断后的收尾)之后执行**一次**,用于校验
    /// 单轮 `validate` 覆盖不到的聚合不变量,例如:
    /// - `visual.like_count == count(visual_like)`;
    /// - 同一 `(user_id, visual_id)` 无重复行;
    /// - 静默后计数归零、缓存与数据库一致。
    ///
    /// 语义:
    /// - 返回空 `Vec` 表示通过;
    /// - 每个 [`InvariantViolation`] 进入 [`crate::ScenarioReport::invariant_failures`],
    ///   不影响 `times` / `failures` / `timeouts` / `validate_failures`,由调用方单独判定;
    /// - 返回 `Err` 会折叠为一条 `reconcile:{kind}` violation,不会静默跳过检查;
    /// - 不计入 RPS 的 `elapsed`,耗时单列在 `reconcile_total`;
    /// - 因优雅关闭而**未启动**的场景不会执行;已启动的场景即使被中断也会执行。
    async fn reconcile(_ctx: &Self::Ctx) -> Result<Vec<InvariantViolation>, Self::Error> {
        Ok(Vec::new())
    }
}