Agent skill · operations · aiskillstore
condition-based-waiting
Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
Why this skill is useful
Provides a generic polling function and patterns for condition-based waiting that improve test reliability and eliminate flaky tests.
What it needs
About 2k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
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 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 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: 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 Requirements: 1. First wait for triggering condition 2. Based on known timing (not guessing) 3. 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
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/condition-based-waiting