🇨🇳中文介绍

基于条件的等待

概述

不稳定的测试通常通过任意延迟来猜测时间。这会产生竞态条件，导致测试在快速机器上通过，但在负载下或 CI 环境中失败。

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

何时使用

digraph when_to_use {
    "Test uses setTimeout/sleep?" [shape=diamond];
    "Testing timing behavior?" [shape=diamond];
    "Document WHY timeout needed" [shape=box];
    "Use condition-based waiting" [shape=box];

    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
}

在以下情况使用：

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

不要在以下情况使用：

• 测试实际的时序行为（防抖、节流间隔）
• 如果使用任意超时，务必记录 WHY

核心模式

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

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

快速模式

实现

通用轮询函数：

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)); // 每 10ms 轮询一次
  }
}

完整的实现及领域特定的辅助函数（waitForEvent、waitForEventCount、waitForEventMatch）请参见 @example.ts。

关于详细模式、实现指南和常见错误，请参阅 @references/patterns-and-implementation.md

实际影响

来自调试会话（2025-10-03）：

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

每周安装量

–

来源

smithery.ai/ski…-waiting

首次出现

–

digraph when_to_use {
    "Test uses setTimeout/sleep?" [shape=diamond];
    "Testing timing behavior?" [shape=diamond];
    "Document WHY timeout needed" [shape=box];
    "Use condition-based waiting" [shape=box];

    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
}