Triage CI Failure
Overview
Systematic workflow for triaging and fixing test failures in CI, especially flaky tests that pass locally but fail in CI. Tests that made it to main are usually flaky due to timing, bundling, or environment differences.
CRITICAL RULE: You MUST run the reproduction workflow before proposing any fixes. No exceptions.
When to Use
- CI test fails on
main branch after PR was merged
- Test passes locally but fails in CI
- Test failure labeled as "flaky" or intermittent
- E2E or integration test timing out in CI only
MANDATORY First Steps
YOU MUST EXECUTE THESE COMMANDS. Reading code or analyzing logs does NOT count as reproduction.
- Extract suite name, test name, and error from CI logs
- EXECUTE: Kill port 3000 to avoid conflicts
- EXECUTE:
pnpm dev $SUITE_NAME (use run_in_background=true)
- EXECUTE: Wait for server to be ready (check with curl or sleep)
- EXECUTE: Run the specific failing test with Playwright directly (npx playwright test test/TEST_SUITE_NAME/e2e.spec.ts:31:3 --headed -g "TEST_DESCRIPTION_TARGET_GOES_HERE")
- If test passes, EXECUTE:
pnpm prepare-run-test-against-prod
- EXECUTE:
pnpm dev:prod $SUITE_NAME and run test again
Only after EXECUTING these commands and seeing their output can you proceed to analysis and fixes.
"Analysis from logs" is NOT reproduction. You must RUN the commands.
Core Workflow
digraph triage_ci {
"CI failure reported" [shape=box];
"Extract details from CI logs" [shape=box];
"Identify suite and test name" [shape=box];
"Run dev server: pnpm dev $SUITE" [shape=box];
"Run specific test by name" [shape=box];
"Did test fail?" [shape=diamond];
"Debug with dev code" [shape=box];
"Run prepare-run-test-against-prod" [shape=box];
"Run: pnpm dev:prod $SUITE" [shape=box];
"Run specific test again" [shape=box];
"Did test fail now?" [shape=diamond];
"Debug bundling issue" [shape=box];
"Unable to reproduce - check logs" [shape=box];
"Fix and verify" [shape=box];
"CI failure reported" -> "Extract details from CI logs";
"Extract details from CI logs" -> "Identify suite and test name";
"Identify suite and test name" -> "Run dev server: pnpm dev $SUITE";
"Run dev server: pnpm dev $SUITE" -> "Run specific test by name";
"Run specific test by name" -> "Did test fail?";
"Did test fail?" -> "Debug with dev code" [label="yes"];
"Did test fail?" -> "Run prepare-run-test-against-prod" [label="no"];
"Run prepare-run-test-against-prod" -> "Run: pnpm dev:prod $SUITE";
"Run: pnpm dev:prod $SUITE" -> "Run specific test again";
"Run specific test again" -> "Did test fail now?";
"Did test fail now?" -> "Debug bundling issue" [label="yes"];
"Did test fail now?" -> "Unable to reproduce - check logs" [label="no"];
"Debug with dev code" -> "Fix and verify";
"Debug bundling issue" -> "Fix and verify";
}
Step-by-Step Process
1. Extract CI Details
From CI logs or GitHub Actions URL, identify:
- Suite name: Directory name (e.g.,
i18n, fields, lexical)
- Test file: Full path (e.g.,
test/i18n/e2e.spec.ts)
- Test name: Exact test description
- Error message: Full stack trace
- Test type: E2E (Playwright) or integration (Vitest)
2. Reproduce with Dev Code
CRITICAL: Always run the specific test by name, not the full suite.
SERVER MANAGEMENT RULES:
- ALWAYS kill all servers before starting a new one
- NEVER assume ports are free
- ALWAYS wait for server ready confirmation before running tests
lsof -ti:3000 | xargs kill -9 2>/dev/null || echo "Port 3000 clear"
pnpm dev $SUITE_NAME
until curl -s http://localhost:3000/admin > /dev/null 2>&1; do sleep 1; done && echo "Server ready"
pnpm exec playwright test test/$SUITE_NAME/e2e.spec.ts -g "exact test name"
pnpm test:int $SUITE_NAME -t "exact test name"
Did the test fail?
- ✅ YES: You reproduced it! Proceed to debug with dev code.
- ❌ NO: Continue to step 3 (bundled code test).
3. Reproduce with Bundled Code
If test passed with dev code, the issue is likely in bundled/production code.
IMPORTANT: You MUST stop the dev server before starting prod server.
lsof -ti:3000 | xargs kill -9 2>/dev/null || echo "Port 3000 clear"
pnpm prepare-run-test-against-prod
pnpm dev:prod $SUITE_NAME
until curl -s http://localhost:3000/admin > /dev/null 2>&1; do sleep 1; done && echo "Server ready"
pnpm exec playwright test test/$SUITE_NAME/e2e.spec.ts -g "exact test name"
pnpm test:int $SUITE_NAME -t "exact test name"
Did the test fail now?
- ✅ YES: Bundling or production build issue. Look for:
- Missing exports in package.json
- Build configuration problems
- Code that behaves differently when bundled
- ❌ NO: Unable to reproduce locally. Proceed to step 4.
4. Unable to Reproduce
If you cannot reproduce locally after both attempts:
- Review CI logs more carefully for environment differences
- Check for race conditions (run test multiple times:
for i in {1..10}; do pnpm test:e2e...; done)
- Look for CI-specific constraints (memory, CPU, timing)
- Consider if it's a true race condition that's highly timing-dependent
Common Flaky Test Patterns
Race Conditions
- Page navigating while assertions run
- Network requests not settled before assertions
- State updates not completed
Fix patterns:
- Use Playwright's web-first assertions (
toBeVisible(), toHaveText())
- Wait for specific conditions, not arbitrary timeouts
- Use
waitForFunction() with condition checks
Test Pollution
- Tests leaving data in database
- Shared state between tests
- Missing cleanup in
afterEach
Fix patterns:
- Track created IDs and clean up in
afterEach
- Use isolated test data
- Don't use
deleteAll that affects other tests
Timing Issues
setTimeout/sleep instead of condition-based waiting- Not waiting for page stability
- Animations/transitions not complete
Fix patterns:
- Use
waitForPageStability() helper
- Wait for specific DOM states
- Use Playwright's built-in waiting mechanisms
Linting Considerations
When fixing e2e tests, be aware of these eslint rules:
playwright/no-networkidle - Avoid waitForLoadState('networkidle') (use condition-based waiting instead)payload/no-wait-function - Avoid custom wait() functions (use Playwright's built-in waits)payload/no-flaky-assertions - Avoid non-retryable assertionsplaywright/prefer-web-first-assertions - Use built-in Playwright assertions
Existing code may violate these rules - when adding new code, follow the rules even if existing code doesn't.
Verification
After fixing:
