用途:解决异步测试中因使用任意延时而导致的偶发失败。测试常靠猜测时间,在快机器上通过、在负载或 CI 中失败,形成竞态条件。本技能主张等待真正关心的条件,而不是猜测耗时。
主要能力:提供通用条件轮询原则与模式,包括等待事件(waitFor(() => events.find(e => e.type === 'DONE')))、等待状态(machine.state === 'ready')、等待数量(items.length >= 5)、等待文件(fs.existsSync(path))以及复合条件(obj.ready && obj.value > 10)。提供带超时与描述的 waitFor 泛型轮询函数,默认每 10ms 轮询、5000ms 超时;并提及 waitForEvent、waitForEventCount、waitForEventMatch 等领域辅助函数(完整实现见 @example.ts)。
适用场景:测试使用 setTimeout、sleep、time.sleep() 等任意延迟;测试偶发失败;并行运行时超时;等待异步操作完成。不适用于测试真实计时行为(防抖、节流间隔),此类情况若仍用任意超时,必须注释说明原因。
使用方式:把文件夹放在相应宿主可见的技能路径中。GitHub Copilot:放在 Copilot 可见的技能路径,或在无法发现文件夹时写入项目说明。Claude Code:放在本地技能目录或兼容插件源。Codex:安装或同步到 $CODEX_HOME/skills/condition-based-waiting,重大更改后重启 Codex。无需 MCP 服务器;无 MCP 时使用回退提示,依靠本地说明、捆绑资源、标准 shell 或编辑器工具及直接验证,并把本地文件、测试、渲染输出、日志或截图作为回退证据,不得声称使用了宿主未暴露的 MCP 操作。
限制与常见错误:轮询过快(如 setTimeout(check, 1))浪费 CPU,建议每 10ms;无超时会无限循环,应始终设置带清晰错误的超时;在循环前缓存状态会产生过期数据,应在循环内调用 getter 获取最新数据。若任意超时确属正确(如工具每 100ms 触发一次、需 2 次触发验证部分输出),应先等待触发条件,再等待已知计时,并注释说明原因。验证协议要求确认请求匹配激活边界、必要输入与依赖已解决、在无虚构工具的前提下完成最小相关工作流、用最相关的本地测试或源证据检查输出,并在首选集成不可用时确认回退安全可行。