Flaky test fix pattern - replaces arbitrary timeouts with condition polling that waits for actual state changes.
Replaces arbitrary test timeouts with condition polling to eliminate flaky race conditions.
npx claudepluginhub lerianstudio/ringThis skill inherits all available tools. When active, it can use any tool Claude has access to.
example.tsFlaky 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.
Decision flow: Test uses setTimeout/sleep? → Testing actual timing behavior? → (yes: document WHY timeout needed) | (no: use condition-based waiting)
Use when: Arbitrary delays (setTimeout, sleep) | Flaky tests (pass sometimes, fail under load) | Timeouts in parallel runs | Async operation waits
Don't use when: Testing actual timing behavior (debounce, throttle) - document WHY if using arbitrary timeout
// ❌ 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();
| 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) |
Generic polling: waitFor(condition, description, timeoutMs=5000) - poll every 10ms, throw on timeout with clear message. See @example.ts for domain-specific helpers (waitForEvent, waitForEventCount, waitForEventMatch).
| ❌ Bad | ✅ Fix |
|---|---|
Polling too fast (setTimeout(check, 1)) | Poll every 10ms |
| No timeout (loop forever) | Always include timeout with clear error |
| Stale data (cache before loop) | Call getter inside loop for fresh data |
await waitForEvent(...); await setTimeout(200) - OK when: (1) First wait for triggering condition (2) Based on known timing, not guessing (3) Comment explaining WHY (e.g., "200ms = 2 ticks at 100ms intervals")
Fixed 15 flaky tests across 3 files: 60% → 100% pass rate, 40% faster execution, zero race conditions.
STOP and report if:
| Decision Type | Blocker Condition | Required Action |
|---|---|---|
| Timing behavior | Test is intentionally testing timing (debounce, throttle) | STOP and document WHY timeout is correct |
| Condition identification | Cannot determine what condition to wait for | STOP and analyze expected state change |
| Timeout configuration | No maximum timeout defined for wait loop | STOP and add timeout with clear error message |
| Polling interval | Polling faster than 10ms without justification | STOP and adjust to 10ms minimum |
The following requirements CANNOT be waived:
| Severity | Condition | Required Action |
|---|---|---|
| CRITICAL | Wait loop without timeout (potential infinite loop) | MUST add timeout immediately |
| CRITICAL | Polling at 1ms intervals (CPU thrashing) | MUST increase to minimum 10ms |
| HIGH | Stale data - condition checked against cached value | MUST move getter call inside loop |
| HIGH | Arbitrary timeout without condition-based wait first | MUST add condition wait before timeout |
| MEDIUM | Timeout error message lacks context | Should add descriptive failure message |
| LOW | Polling interval could be optimized | Fix in next iteration |
| User Says | Your Response |
|---|---|
| "Just increase the timeout, the test is flaky" | "Increasing timeouts masks race conditions. MUST identify actual condition to wait for instead." |
| "Adding a small sleep is simpler" | "Arbitrary sleeps cause flaky tests. MUST wait for the actual state change condition." |
| "The 10ms polling is too slow" | "Polling faster than 10ms risks CPU thrashing. MUST justify with documented performance requirement." |
| "We don't need a timeout, it will always complete" | "CANNOT have wait loops without timeout. Infinite loops are FORBIDDEN - add max timeout." |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "A small sleep is good enough for this test" | Arbitrary delays cause flaky tests under load | MUST use condition-based waiting |
| "Polling every 1ms will be faster" | CPU thrashing harms overall test performance | MUST use minimum 10ms interval |
| "This will always complete quickly" | Assumptions about timing fail in CI/parallel runs | MUST add timeout with error message |
| "The timeout handles the failure case" | Timeout masks root cause; condition reveals intent | MUST wait for condition, timeout is safety net |
| "Test is testing timing, so timeout is fine" | Timing tests still need documented justification | MUST document WHY timeout is correct |
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.