$ ~/registry/skill/obra-testing-condition-based-waiting

SKILL

Condition-Based Waiting

Name: Condition-Based Waiting
Author: obra

Replace fixed delays with condition polling for more reliable async tests.

Stars

★ 40

Source

GitHub

Updated

2026-07-05

// securityLow risk

Prompt only, no code
Open source

Running security audit…

Credentials
Network egress
Code execution
Data access
Supply chain

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "Condition-Based Waiting" skill from askskill:
1. Download https://raw.githubusercontent.com/obra/clank/main/skills/testing/condition-based-waiting/SKILL.md
2. Save it as ~/.claude/skills/condition-based-waiting/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Wait for an element to appear before asserting

Prompt

Please rewrite this frontend test that uses sleep(3000) into condition-based waiting: keep checking whether the “Submission successful” message appears, use a reasonable timeout and polling interval, and return a clear error message on timeout.

Expected

Rewritten test code that uses condition polling to wait for the message, including timeout handling and clearer failure messages.

Wait for a background job to finish

Prompt

I have an integration test that waits a fixed 10 seconds after triggering an export job. Please change it to poll the job status API until the status becomes completed or failed, and provide a reusable wait helper.

Expected

A test example with a reusable wait helper that determines job completion by polling the status API instead of relying on fixed delays.

Stabilize async data synchronization checks

Prompt

Please refactor this test: after writing data, do not wait 5 seconds before querying the database; instead, repeatedly check whether the target record exists and whether the field values are correct. Also explain why this approach is more stable.

Expected

Refactored test logic that checks database state conditionally, plus a brief explanation of why it is more stable and reduces flaky failures.

// docs

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

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

// ❌ 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
Wait for event	`waitFor(() => events.find(e => e.type === 'DONE'))`
Wait for state	`waitFor(() => machine.state === 'ready')`
Wait for count	`waitFor(() => items.length >= 5)`
Wait for file	`waitFor(() => fs.existsSync(path))`
Complex condition	`waitFor(() => obj.ready && obj.value > 10)`

Implementation

Generic polling function:

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)); // Poll every 10ms
  }
}

See @example.ts for complete implementation with domain-specific helpers (waitForEvent, waitForEventCount, waitForEventMatch) from actual debugging session.

Common Mistakes

❌ Polling too fast: setTimeout(check, 1) - wastes CPU ✅ Fix: Poll every 10ms

❌ No timeout: Loop forever if condition never met ✅ Fix: Always include timeout with clear error

❌ Stale data: Cache state before loop ✅ Fix: Call getter inside loop for fresh data

When Arbitrary Timeout IS Correct

// Tool ticks every 100ms - need 2 ticks to verify partial output
await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
// 200ms = 2 ticks at 100ms intervals - documented and justified

Requirements:

First wait for triggering condition
Based on known timing (not guessing)
Comment explaining WHY

Real-World Impact

From debugging session (2025-10-03):

Fixed 15 flaky tests across 3 files
Pass rate: 60% → 100%
Execution time: 40% faster
No more race conditions

obraGet→

$ loading_