Condition-Based Waiting

Use with: writing-tests skill for overall test guidance. This skill focuses on timing-based flakiness.

Related: If tests pass alone but fail concurrently, the problem may be shared state, not timing. See fixing-flaky-tests skill for diagnosis.

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

Test has arbitrary delay (setTimeout/sleep)?
    │
    ├─ Testing actual timing (debounce, throttle)?
    │   └─ Yes → Keep timeout, document WHY
    │
    └─ No → Replace with condition-based waiting

Use when:

• Tests have arbitrary delays (setTimeout, sleep, time.sleep())
• Tests are flaky with timing-related errors
• Waiting for async operations to complete

Don't use when:

• Testing actual timing behavior (debounce, throttle, intervals)
• Problem is shared state between tests (use fixing-flaky-tests)

Core pattern

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

// Good: Waiting for condition (returns the result)
const result = await waitFor(() => getResult(), 'result to be available');
expect(result).toBeDefined();

Implementation

Prefer framework built-ins when available:

• Testing Library: findBy queries, waitFor
• Playwright: auto-waiting, expect(locator).toBeVisible()
• pytest: asyncio.wait_for, tenacity

Custom polling fallback when built-ins aren't enough:

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, 50));  // Poll interval
  }
}

Common use cases:

• waitFor(() => events.find(e => e.type === 'DONE'), 'done event')
• waitFor(() => machine.state === 'ready', 'ready state')
• waitFor(() => items.length >= 5, '5+ items')

Language-specific patterns

Stack	Reference
Python (pytest, asyncio, tenacity)	references/python.md
TypeScript (Jest, Testing Library, Playwright)	references/typescript.md

Common mistakes

Mistake	Problem	Fix
Polling too fast	setTimeout(check, 1) wastes CPU	Poll every 50ms
No timeout	Loop forever if condition never met	Always include timeout
Stale data	Caching state before loop	Call getter inside loop
No description	"Timeout" with no context	Include what you waited for

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:

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