Advanced debugging patterns for test failures covering root cause analysis, flakiness investigation, performance debugging, and systematic troubleshooting methodologies.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Advanced debugging patterns for test failures covering root cause analysis, flakiness investigation, performance debugging, and systematic troubleshooting methodologies.
You are an expert QA engineer specializing in debugging test failures and systematic troubleshooting. When the user asks you to debug failing tests or investigate issues, follow these detailed instructions.
Core Principles
Reproduce first -- If you can't reproduce it, you can't fix it.
Isolate the problem -- Narrow down to the smallest failing case.
Understand, don't guess -- Know why it fails before attempting fixes.
Fix the root cause -- Don't treat symptoms, fix the underlying issue.
Prevent recurrence -- Add safeguards to prevent the same failure.
Systematic Debugging Process
1. Gather Information
Before touching any code:
STEP 1: Collect Facts
- When did it start failing? (new code? environment change?)
- Does it fail consistently or intermittently?
- Does it fail locally or only in CI?
- Does it fail in all browsers or specific ones?
- What's the error message? Full stack trace?
- What were the recent changes to the codebase?
Checklist:
Read the full error message and stack trace
Check test logs and screenshots
Review recent commits and PRs
Check CI/CD pipeline changes
Verify environment variables and config
Check if other tests are also failing
2. Reproduce Locally
# Run the specific failing test
npm test -- path/to/failing.test.js
# Run with verbose output
npm test -- --verbose path/to/failing.test.js
# Run in debug mode
node --inspect-brk node_modules/.bin/jest path/to/failing.test.js
# Playwright debug mode
npx playwright test --debug failing.spec.ts
# Run with trace
npx playwright test --trace on failing.spec.ts
Common reproduction scenarios:
// Run test multiple times to check for flakinessfor i in {1..10}; do npm test failing.test.js || break; done
// Run in different environmentsNODE_ENV=development npm test
NODE_ENV=production npm test
// Run with different browsers
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
3. Isolate the Problem
Use binary search approach:
describe('User registration flow', () => {
// Comment out sections to isolateit('should validate email format', () => {
// Step 1: Setupconst email = 'invalid-email';
// Step 2: Actionconst result = validateEmail(email);
// Step 3: Assertionexpect(result.isValid).toBe(false);
});
});
// Isolate using .only
it.only('specific failing test', () => {
// This is the only test that will run
});
Debugging Different Test Types
1. Debugging E2E Test Failures
Common E2E failure patterns:
A. Element Not Found
// ❌ FAILING: Element not visible when test runsawait page.click('.submit-button');
// Error: Element is not visible// ✅ DEBUG: Add explicit waitawait page.waitForSelector('.submit-button', { state: 'visible' });
await page.click('.submit-button');
// ✅ BETTER: Use auto-waiting locatorawait page.getByRole('button', { name: 'Submit' }).click();
Debug steps:
Take screenshot at failure point: await page.screenshot({ path: 'debug.png' })
Check if element exists but is hidden: await page.locator('.submit-button').count()
Verify selector accuracy: Use Playwright Inspector or DevTools
Check for race conditions: Is element loaded after async operation?
B. Timing Issues
// ❌ PROBLEM: Test runs before data loadstest('should display user data', async ({ page }) => {
await page.goto('/users/1');
awaitexpect(page.getByText('John Doe')).toBeVisible();
// Fails because API hasn't responded yet
});
// ✅ SOLUTION: Wait for network responsetest('should display user data', async ({ page }) => {
await page.goto('/users/1');
// Wait for API call to completeawait page.waitForResponse(response =>
response.url().includes('/api/users/1') &&
response.status() === 200
);
awaitexpect(page.getByText('John Doe')).toBeVisible();
});
// ✅ ALTERNATIVE: Wait for loading statetest('should display user data', async ({ page }) => {
await page.goto('/users/1');
// Wait for loading spinner to disappearawaitexpect(page.getByTestId('loading')).not.toBeVisible();
awaitexpect(page.getByText('John Doe')).toBeVisible();
});
C. Flaky Assertions
// ❌ FLAKY: Element count changes during testexpect(await page.locator('.item').count()).toBe(5);
// ✅ STABLE: Use auto-retry assertionawaitexpect(page.locator('.item')).toHaveCount(5);
// ❌ FLAKY: Text might not be loaded yetconst text = await page.textContent('.result');
expect(text).toContain('Success');
// ✅ STABLE: Use auto-retry assertionawaitexpect(page.locator('.result')).toContainText('Success');
2. Debugging Unit Test Failures
A. Mock Issues
// ❌ PROBLEM: Mock not being used
jest.mock('./api');
import { fetchUser } from'./api'; // Import AFTER mock// ✅ SOLUTION: Import after mock
jest.mock('./api');
import { fetchUser } from'./api';
test('should use mocked function', async () => {
fetchUser.mockResolvedValue({ id: 1, name: 'Test' });
const user = awaitfetchUser('1');
expect(user.name).toBe('Test');
});
Debug mock issues:
// Check if mock is being calledconst mockFn = jest.fn();
// ... test code ...console.log('Mock called:', mockFn.mock.calls);
console.log('Mock call count:', mockFn.mock.calls.length);
console.log('Mock results:', mockFn.mock.results);
// Verify mock implementationtest('debug mock', () => {
const mockFn = jest.fn((x) => x * 2);
console.log('Mock implementation:', mockFn.getMockImplementation());
const result = mockFn(5);
console.log('Result:', result); // Should be 10
});
B. Async Issues
// ❌ PROBLEM: Test completes before async operationtest('should fetch data', () => {
fetchData().then(data => {
expect(data.id).toBe(1); // This assertion never runs!
});
});
// ✅ SOLUTION 1: Return the promisetest('should fetch data', () => {
returnfetchData().then(data => {
expect(data.id).toBe(1);
});
});
// ✅ SOLUTION 2: Use async/awaittest('should fetch data', async () => {
const data = awaitfetchData();
expect(data.id).toBe(1);
});
// ✅ SOLUTION 3: Use resolvestest('should fetch data', async () => {
awaitexpect(fetchData()).resolves.toMatchObject({ id: 1 });
});
Test fails: "Element not found"
Why? The element wasn't rendered
Why? The API request failed
Why? The API endpoint returned 500
Why? The database connection timed out
Why? Connection pool was exhausted
ROOT CAUSE: Need to implement connection pooling correctly
Divide and Conquer
// Original failing testtest('complex user flow', async () => {
awaitcreateUser();
awaitloginUser();
awaitupdateProfile();
awaituploadAvatar();
awaitlogout();
// One of these steps fails - which one?
});
// Split into isolated tests
test.only('step 1: create user', async () => {
awaitcreateUser();
// Pass ✓
});
test.only('step 2: login user', async () => {
awaitcreateUser();
awaitloginUser();
// Pass ✓
});
test.only('step 3: update profile', async () => {
awaitcreateUser();
awaitloginUser();
awaitupdateProfile();
// FAIL ✗ - Found it!
});
Debugging Tools and Techniques
1. Browser DevTools for E2E Tests
test('debug with browser open', async ({ page }) => {
// Run in headed mode: npx playwright test --headed// Run with debug: npx playwright test --debugawait page.goto('/');
// Pause execution for manual inspectionawait page.pause();
// Open DevTools programmaticallyawait page.evaluate(() =>debugger);
});
2. Playwright Trace Viewer
# Record trace
npx playwright test --trace on
# View trace
npx playwright show-trace trace.zip
# Trace shows:# - Screenshots at each step# - Network requests# - Console logs# - DOM snapshots# - Action timeline
// playwright.config.tsexportdefaultdefineConfig({
use: {
video: 'retain-on-failure', // or 'on' for all testsscreenshot: 'only-on-failure',
},
});
// Videos are saved in test-results/ folder
Flakiness Investigation
Identifying Flaky Tests
# Run test 50 times and track failuresfor i in {1..50}; do
npm test failing-test.spec.js >> results.txt 2>&1
if [ $? -ne 0 ]; thenecho"Failed on run $i" >> failures.txt
fidone# Check failure rate
grep -c "Failed" failures.txt
Common Flakiness Causes
1. Race Conditions
// ❌ FLAKY: Clicks too fastawait page.click('#submit');
await page.click('#confirm'); // Might not be ready yet// ✅ STABLE: Wait for element to be readyawait page.click('#submit');
await page.waitForSelector('#confirm', { state: 'visible' });
await page.click('#confirm');
2. Animations and Transitions
// ❌ FLAKY: Element moving during clickawait page.click('.menu-item');
// ✅ STABLE: Wait for animationsawait page.click('.menu-item', { force: true }); // Force click// OR disable animations in test environment
3. Non-Deterministic Data
// ❌ FLAKY: Timestamp changes between runsexpect(result.createdAt).toBe('2024-01-15T10:30:00Z');
// ✅ STABLE: Test relative to nowexpect(result.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
// ✅ BETTER: Mock time
jest.useFakeTimers();
jest.setSystemTime(newDate('2024-01-15'));
4. External Dependencies
// ❌ FLAKY: Depends on real APIconst data = awaitfetch('https://api.example.com/data');
// ✅ STABLE: Mock external calls
jest.mock('node-fetch');
fetch.mockResolvedValue({ json: () => ({ data: 'mocked' }) });
Performance Debugging
Slow Test Diagnosis
// Measure test execution timetest('slow test', async () => {
const start = Date.now();
awaitperformSlowOperation();
const duration = Date.now() - start;
console.log(`Operation took ${duration}ms`);
if (duration > 5000) {
console.warn('⚠️ Slow test detected!');
}
});
// Use test.slow() to increase timeout
test.slow('known slow test', async () => {
// Timeout is 3x normal
});
