condition-based-waiting

Condition-Based Waiting

Scope

Replace sleep N with polled-condition waits. Every wait MUST have a timeout, a condition, and a failure path.

The Rule

❌ sleep 5        ← hope-based; either too short (flake) or too long (slow)
✅ wait_for <condition> --timeout 10s --interval 0.5s || fail <msg>

Canonical Patterns

Wait for HTTP health

for i in {1..30}; do
  curl -sf http://localhost:3000/health && break
  sleep 1
done
curl -sf http://localhost:3000/health || { echo "server never came up"; exit 1; }

Wait for DB migration to apply

for i in {1..20}; do
  psql "$DATABASE_URL" -tc "SELECT 1 FROM information_schema.tables WHERE table_name='user_preferences'" \
    | grep -q 1 && break
  sleep 0.5
done
psql "$DATABASE_URL" -tc "SELECT 1 FROM information_schema.tables WHERE table_name='user_preferences'" \
  | grep -q 1 || { echo "migration never applied"; exit 1; }

Wait for a file to appear

for i in {1..30}; do
  [ -s e2e-evidence/vgN-out.json ] && break
  sleep 0.5
done
[ -s e2e-evidence/vgN-out.json ] || { echo "output never written"; exit 1; }

Wait for a log line

timeout 15 tail -F app.log | grep -m1 "Server ready" || { echo "server ready never logged"; exit 1; }

Wait for a DOM condition (Playwright / agent-browser)

# agent-browser: wait for text to appear
agent-browser wait-for-text "Welcome" --timeout 10000

# Playwright JS API equivalent
await page.getByText('Welcome').waitFor({ timeout: 10000 });

Wait for email delivery (Resend / MailHog)

for i in {1..30}; do
  EMAIL=$(curl -s -H "Authorization: Bearer $RESEND_API_KEY" \
    "https://api.resend.com/emails/$LAST_EMAIL_ID" | jq -r .last_event)
  [ "$EMAIL" = "delivered" ] && break
  sleep 2
done
[ "$EMAIL" = "delivered" ] || { echo "email never delivered"; exit 1; }

Timeout Guidance

Operation	Default timeout	Interval
DB ready	10s	0.5s
Dev server cold start	30s	1s
Simulator boot	60s	2s
Migration apply	10s	0.5s
Email delivery	60s	2s
Background job	30s	1s

Override per-project when known. NEVER use sleep with a guess.

Anti-Patterns

• sleep 5 followed by assertion → either flakes (too short) or slows runs (too long)
• Polling without a timeout → infinite hang on failure
• Polling without a failure path → silent green that masks breakage
• Polling at 10ms intervals for slow operations → wasted CPU
• Polling at 60s intervals for fast operations → wasted wall-clock

Rules

1. Every wait must have: timeout, interval, condition, failure message
2. Never use bare sleep for "wait for X to happen"
3. Sleep is OK for simulating user think-time in UI flows (explicit, e.g., sleep 2 # read the success toast)
4. Log the waited-on condition before polling — aids debugging

Security Policy

Pure timing utility. No state modification.