condition-based-waiting

Replace arbitrary test sleeps with condition-based polling loops.

130|8|Updated Jan 23, 2026
One-click install
npx skills add https://github.com/sandgardenhq/sgai --skill condition-based-waiting-sandgardenhq
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: condition-based-waiting
Source: https://github.com/sandgardenhq/sgai/tree/main/cmd/sgai/skel/.sgai/skills/condition-based-waiting
Command: npx skills add https://github.com/sandgardenhq/sgai --skill condition-based-waiting-sandgardenhq

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Flaky tests caused by arbitrary timeouts, race conditions, and timing dependencies undermine confidence and waste CI time. This Skill replaces guesswork sleeps with condition-based waiting so tests synchronize on actual system state changes.

Core Features & Use Cases

  • Condition Polling Pattern: Swap setTimeout/sleep with a waitFor(condition, description, timeoutMs) loop that polls at sane intervals and fails clearly on timeout.
  • Targeted Helpers: Encourages domain-specific waits (events, state readiness, counts, file existence) to stabilize async tests across environments.
  • Documented Exceptions: When real timing behavior must be tested (e.g., debounce windows), requires explicit justification and comments to keep intent clear.

Quick Start

Ask me to replace arbitrary sleeps in failing tests with a waitFor-based condition check and add a clear timeout with an error message describing the awaited state.

Frequently Asked Questions about condition-based-waiting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix flaky tests caused by race conditions in async CI runs?

Flaky tests caused by race conditions are fixed by replacing arbitrary setTimeout sleeps with condition-based polling using a waitFor loop. This synchronizes tests on actual state changes, bounding waits with descriptive timeouts and sensible polling intervals for deterministic outcomes.

What is the best way to wait for asynchronous state readiness without arbitrary sleeps?

Condition-based waiting replaces guesswork sleeps by polling for state readiness. A waitFor function checks the condition at sane intervals and fails clearly on timeout, ensuring tests synchronize on real system changes rather than fixed delays.

How do I eliminate arbitrary timeouts when testing event emission and I/O completion?

To eliminate arbitrary timeouts, swap fixed sleeps with targeted condition checks for event emission and I/O completion. Using domain-specific polling enforces bounded waits with descriptive error messages, preventing race conditions across parallel environments.

When should I use real timing behavior instead of condition-based polling in async tests?

Real timing behavior is reserved for testing actual timing mechanics like debounce windows. When required, it demands explicit justification and comments to clarify intent, keeping the exception visible and preventing accidental flakiness from reintroduced sleeps.

Does condition-based waiting work for parallel CI runs and background processing?

Yes, condition-based waiting stabilizes parallel CI runs and background processing by polling for fresh state retrieval. It enforces bounded waits with sensible polling intervals, ensuring reliable synchronization across varied execution environments.

Why do my async tests still fail intermittently even with sleep delays?

Async tests fail intermittently because arbitrary sleep delays do not guarantee system state changes have completed. Condition-based polling resolves this by continuously checking state readiness and failing with descriptive timeouts when conditions are not met.