Agent skill · software engineering · aaaaqwq
Condition-Based Waiting
Replace arbitrary timeouts with condition polling for reliable async tests
Why this skill is useful
Provides a generic polling function and specific patterns for condition-based waiting that improve test reliability and reduce race conditions.
What it needs
About 2k tokens when loaded. Last updated 2026-08-06. 83 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 aaaaqwq/sp-condition-based-waiting