name: condition-based-waiting description: 当测试具有竞态条件、时序依赖或不一致的通过/失败行为时使用 - 用条件轮询替代任意超时，等待实际状态变化，消除基于时序猜测的不稳定测试

条件基础等待

概述

不稳定测试常常通过任意延迟来猜测时序。这创建了竞态条件，使得测试在快速机器上通过但在负载下或CI中失败。

核心原则： 等待你关心的实际条件，而不是猜测需要多长时间。

何时使用

digraph when_to_use {
    "测试使用setTimeout/sleep？" [shape=diamond];
    "测试时序行为？" [shape=diamond];
    "记录为什么需要超时" [shape=box];
    "使用条件基础等待" [shape=box];

    "测试使用setTimeout/sleep？" -> "测试时序行为？" [label="是"];
    "测试时序行为？" -> "记录为什么需要超时" [label="是"];
    "测试时序行为？" -> "使用条件基础等待" [label="否"];
}

使用时机：

测试有任意延迟（setTimeout, sleep, time.sleep()）
测试不稳定（有时通过，在负载下失败）
测试在并行运行时超时
等待异步操作完成

不使用时：

测试实际时序行为（防抖、节流间隔）
如果使用任意超时，始终记录为什么

核心模式

// ❌ 之前：猜测时序
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ 之后：等待条件
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

快速模式

场景	模式
等待事件	`waitFor(() => events.find(e => e.type === 'DONE'))`
等待状态	`waitFor(() => machine.state === 'ready')`
等待计数	`waitFor(() => items.length >= 5)`
等待文件	`waitFor(() => fs.existsSync(path))`
复杂条件	`waitFor(() => obj.ready && obj.value > 10)`

实现

通用轮询函数：

async function waitFor<T>(
  condition: () => T | undefined | null | false,
  description: string,
  timeoutMs = 5000
): Promise<T> {
  const startTime = Date.now();

  while (true) {
    const result = condition();
    if (result) return result;

    if (Date.now() - startTime > timeoutMs) {
      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
    }

    await new Promise(r => setTimeout(r, 10)); // 每10毫秒轮询一次
  }
}

参见 @example.ts 获取完整实现，包括从实际调试会话中提取的领域特定助手（waitForEvent, waitForEventCount, waitForEventMatch）。

常见错误

❌ 轮询太快： setTimeout(check, 1) - 浪费CPU
✅ 修复： 每10毫秒轮询一次

❌ 无超时： 如果条件从未满足，循环永远运行
✅ 修复： 始终包含超时，并带有清晰错误

❌ 陈旧数据： 在循环前缓存状态
✅ 修复： 在循环内调用获取器以获取新鲜数据

当任意超时是正确的时

// 工具每100毫秒滴答一次 - 需要2次滴答以验证部分输出
await waitForEvent(manager, 'TOOL_STARTED'); // 首先：等待触发条件
await new Promise(r => setTimeout(r, 200));   // 然后：等待时序行为
// 200毫秒 = 在100毫秒间隔下的2次滴答 - 记录并证明合理

要求：

首先等待触发条件
基于已知时序（非猜测）
注释解释为什么

实际影响

从调试会话（2025-10-03）：

修复了3个文件中的15个不稳定测试
通过率：60% → 100%
执行时间：快40%
无更多竞态条件