Condition Based Waiting

Replace arbitrary timeouts with condition polling for reliable async tests

43 stars 26 forksTesting & QA

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add obra/clank --skill Condition-Based Waiting
Manual install
git clone --depth 1 https://github.com/obra/clank.git /tmp/clank
mkdir -p ~/.claude/skills
cp -r /tmp/clank/skills/testing/condition-based-waiting ~/.claude/skills/Condition-Based-Waiting

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Condition-Based Waiting

## Overview

Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.

**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.

## When to Use

```dot
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"];
}
```

**Use when:**
- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
- Tests are flaky (pass sometimes, fail under load)
- Tests timeout when run in parallel
- Waiting for async operations to complete

**Don't use when:**
- Testing actual timing behavior (debounce, throttle intervals)
- Always document WHY if using arbitrary timeout

## Core Pattern

```typescript
// ❌ BEFORE: Guessing at timing
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ AFTER: Waiting for condition
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();
```

## Quick Patterns

| Scenario | Pattern |
Read the full skill on GitHub

Details

Skill name
Condition-Based Waiting
Repository
obra/clank
Path
skills/testing/condition-based-waiting/SKILL.md
Repo updated
9 October 2025

FAQ

What does the Condition Based Waiting skill do?

Replace arbitrary timeouts with condition polling for reliable async tests

How do I install the Condition Based Waiting skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add obra/clank --skill Condition-Based Waiting. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Condition Based Waiting popular?

It lives in obra/clank, which has 43 GitHub stars and 26 forks.

Related skills

Browse the most popular Claude skills, all testing & qa skills, or write your own with the skills generator.