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(`超时等待 ${description} 超过 ${timeoutMs}ms`);
    }

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

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

常见错误

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

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

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

当任意超时是正确的时候

// 工具每100ms滴答一次 - 需要2次滴答来验证部分输出
await waitForEvent(manager, 'TOOL_STARTED'); // 第一步：等待条件
await new Promise(r => setTimeout(r, 200));   // 然后：等待时间行为
// 200ms = 100ms间隔的2次滴答 - 记录并合理解释

要求：

首先等待触发条件
基于已知时间（非猜测）
注释解释原因

实际影响

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

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