flaky-test

name	flaky-test
description	Diagnose and fix flaky tests. Use when a test passes sometimes and fails other times.

Skill: Fix Flaky Tests

Trigger

When a test is flaky — passes intermittently, fails on CI but not locally, or depends on timing/order.

Steps

Step 1: Reproduce

• Run the test 10+ times: {{CONFIG.testing.testCommand}} -- --testPathPattern={file} --runInBand
• Note failure rate and any pattern (e.g., fails when run with others)
• Run in isolation vs with full suite to check order dependency

Step 2: Categorize

Common causes:

• Timing — Async not awaited; setTimeout/setInterval; race conditions
• Shared state — Mocks, globals, or DB state leaking between tests
• Randomness — Date.now(), Math.random(), uuid without seed
• Order dependency — Tests assume execution order; shared fixtures
• Environment — CI vs local (timezone, env vars, network)

Step 3: Fix

Timing

• Add await for all async operations
• Use waitFor or act for React updates
• Replace setTimeout with fake timers: jest.useFakeTimers()
• Increase timeout only as last resort; prefer fixing the race

Shared State

• Reset mocks in beforeEach: jest.clearAllMocks() or mockReset()
• Use beforeEach to create fresh fixtures; avoid module-level state
• Run tests with --runInBand to isolate; fix root cause rather than rely on it

Randomness

• Mock Date.now(), Math.random(), or ID generators
• Use jest.setSystemTime() for date-dependent tests
• Seed random if deterministic output is needed

Order Dependency

• Make each test self-contained; no assumptions about other tests
• Use beforeEach for setup; avoid afterAll that affects later tests

Step 4: Verify

• Run test 20+ times: for i in {1..20}; do {{CONFIG.testing.testCommand}} -- --testPathPattern={file}; done
• Run with full suite to ensure no regression
• Check CI passes on multiple runs

Completion

• Test passes consistently (20/20 runs)
• No new flakiness introduced
• Root cause fixed, not masked (e.g., no arbitrary sleep)