condition-based-waiting

Condition-Based Waiting

Skill Usage Announcement

MANDATORY: When using this skill, announce it at the start with:

🔧 Using Skill: condition-based-waiting | [brief purpose based on context]

Example:

🔧 Using Skill: condition-based-waiting | [Provide context-specific example of what you're doing]

This creates an audit trail showing which skills were applied during the session.

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)
• Event-based systems available (see "When NOT to Poll" below)
• Always document WHY if using arbitrary timeout

When NOT to Poll

Polling is NOT appropriate when:

1. Event-Based Systems Available

Use event listeners instead of polling for:

• WebSockets / Server-Sent Events
• EventEmitter / Message Bus
• DOM events (click, change, etc.)
• Process signals (SIGTERM, etc.)

Example:

// ❌ BAD: Polling for WebSocket message
let lastMessage;
ws.on('message', msg => lastMessage = msg);
await waitForCondition(() => lastMessage?.type === 'ready');

// ✅ GOOD: Event-based waiting
await new Promise((resolve, reject) => {
  const timeout = setTimeout(() => reject(new Error('Timeout')), 5000);
  ws.once('message', (msg) => {
    if (msg.type === 'ready') {
      clearTimeout(timeout);
      resolve(msg);
    }
  });
});