condition-based-waiting
/condition-based-waiting
Zastępuje arbitralne limity czasu w testach czekaniem na faktyczny stan, co usuwa niestabilność wynikającą z zgadywanych opóźnień.
- Autor
- NickCrew ↗
- Repozytorium
- Claude-Cortex ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 28.06.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 28.06.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: example.ts
Co robi i kiedy
Zastępuje arbitralne limity czasu w testach czekaniem na faktyczny stan, co usuwa niestabilność wynikającą z zgadywanych opóźnień.
Oryginalny opis (EN)
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
Jak działa
- Overview
- When to Use
- Core Pattern
- Quick Patterns
- Implementation
- Common Mistakes
- When Arbitrary Timeout IS Correct
- Real-World Impact
Podgląd SKILL.md
---
name: condition-based-waiting
description: 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
keywords:
- asynchronous
- condition
- event-driven
- polling
- wait
file_patterns:
- '**/*.ts'
- '**/*.tsx'
- '**/package.json'
- '**/tsconfig.json'
confidence: 0.68
---
# 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
```dot
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)
- Always document WHY if using arbitrary timeout
## Core Pattern
```typescript
// ❌ BEFORE: Guessing at timing
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();
// ✅ AFTER: Waiting for condition
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();
```
## 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:
```typescript
async function waitFor<T>(
condition: () => T | undefined | null | false,
description: string,
timeoutMs = 5000
): Promise<T> {
const startTime = Date.now();
while (true) {
const result = condition();
if (result) return result;
if (Date.now() - startTime > timeoutMs) {
throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
}
await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
}
}
```
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
```typescript
// Tool ticks every 100ms - need 2 ticks to verify partial output
await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
// 200ms = 2 ticks at 100ms intervals - documented and justified
```
**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
Pliki w paczce (2)
- SKILL.md 4 KB
- example.ts 5 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · NickCrew/Claude-Cortex | 100 | MIT |
| kbluck/agent-resources | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 8b3dcc4f2599 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100stack-testing
Podpowiada dyscyplinę testów na prawdziwym systemie dla pytest, Go, C++, Django, Spring Boot i FastAPI, także przy e2e w przeglądarce. - 100axiom-analyze-test-failures
Diagnozuje, dlaczego testy zawodzą: niestabilne testy, testy przechodzące lokalnie i padające w CI oraz wyścigi w testach. - 100contributing
Prowadzi przez workflow wkładu w Race Condition: konfigurację hooków pre-commit, testy przed PR i wymagania dotyczące stylu kodu. - 100deadlock-race-condition-troubleshooting
Wykrywa i odtwarza subtelne wyścigi w wielowątkowym kodzie oraz zakleszczenia wynikające z kolejności blokad. - 100general-create-condition
Tworzy nowy warunek rozszerzenia sterujący tym, kiedy rozszerzenia są aktywne, na podstawie stanu aplikacji, np. sekcji, uprawnień, stanu encji lub kontekstu przestrzeni roboczej. - 100getting-started
Prowadzi przez uruchomienie projektu Race Condition od sklonowania do działającej symulacji: instalacja zależności, poświadczenia GCP i rozwiązywanie problemów ze startem.