Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

debugging/debugging.md

View on GitHub
# Debugging & Troubleshooting

## Table of Contents

1. [Debug Tools](#debug-tools)
2. [Trace Viewer](#trace-viewer)
3. [Identifying Flaky Tests](#identifying-flaky-tests)
4. [Debugging Network Issues](#debugging-network-issues)
5. [Debugging in CI](#debugging-in-ci)
6. [Debugging Authentication](#debugging-authentication)
7. [Debugging Screenshots](#debugging-screenshots)
8. [Common Issues](#common-issues)
9. [Logging](#logging)

## Debug Tools

### Playwright Inspector

```bash
# Run with inspector
PWDEBUG=1 npx playwright test
# Or specific test
PWDEBUG=1 npx playwright test login.spec.ts
```

Features:

- Step through test actions
- Pick locators visually
- Inspect DOM state
- Edit and re-run

### Headed Mode

```bash
# Run with visible browser
npx playwright test --headed

# Interactive debugging (headed, paused, step-through)
npx playwright test --debug
```

You can also set `slowMo` to add an `N` ms delay per action, making test execution easier to follow while debugging.

```typescript
// playwright.config.ts
export default defineConfig({
	use: {
		launchOptions: {
			slowMo: 500
		}
	}
});
```

### UI Mode

```bash
# Interactive test runner
npx playwright test --ui
```

Features:

- Watch mode
- Test timeline
- DOM snapshots
- Network logs
- Console logs

### Debug in Code

```typescript
test('debug example', async ({ page }) => {
	await page.goto('/');

	// Pause and open inspector
	await page.pause();

	// Continue test...
	await page.click('button');
});
```

## Trace Viewer

### Enable Traces

```typescript
// playwright.config.ts
export default defineConfig({
	use: {
		trace: 'on-first-retry' // Record on retry
		// trace: 'on',                 // Always record
		// trace: 'retain-on-failure',  // Keep only failures
	}
});
```

### View Traces

```bash
# Open trace file
npx playwright show-trace trace.zip

# From test-results
npx playwright show-trace test-results/test-name/trace.zip
```

### Trace Contents

- Screenshots at each action
- DOM snapshots
- Network requests/responses
- Console logs
- Action timeline
- Source code

### Programmatic Traces

```typescript
test('manual trace', async ({ page, context }) => {
	await context.tracing.start({ screenshots: true, snapshots: true });

	await page.goto('/');
	await page.click('button');

	await context.tracing.stop({ path: 'trace.zip' });
});
```

## Identifying Flaky Tests

If a test fails intermittently, it's likely flaky. Quick checks:

| Behavior                               | Likely Cause                  | Next Step                                    |
| -------------------------------------- | ----------------------------- | -------------------------------------------- |
| Fails sometimes, passes other times    | Flaky - timing/race condition | [flaky-tests.md](flaky-tests.md)             |
| Fails only with multiple workers       | Flaky - parallelism/isolation | [flaky-tests.md](flaky-tests.md)             |
| Fails only in CI                       | Environment difference        | [CI Debugging](#debugging-in-ci) below       |
| Always fails                           | Bug in test or app            | Debug with tools above                       |
| Always passes locally, always fails CI | CI-specific issue             | [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) |

> **For flaky test detection commands, root cause analysis, and fixing strategies**, see [flaky-tests.md](flaky-tests.md).

## Debugging Network Issues

### Monitor All Requests

```typescript
test('debug network', async ({ page }) => {
	const requests: string[] = [];
	const failures: string[] = [];

	page.on('request', (req) => requests.push(`>> ${req.method()} ${req.url()}`));
	page.on('requestfinished', (req) => {
		const resp = req.response();
		requests.push(`<< ${resp?.status()} ${req.url()}`);
	});
	page.on('requestfailed', (req) => {
		failures.push(`FAILED: ${req.url()} - ${req.failure()?.errorText}`);
	});

	await page.goto('/dashboard');

	// Log summary
	console.log('Requests:', requests.length);
	if (failures.length) console.log('Failures:', failures);
});
```

### Wait for Specific API Response

When debugging network-dependent issues, wait for specific API responses instead of arbitrary timeouts.

```typescript
// Start waiting BEFORE triggering the request
const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/data') && resp.status() === 200);
await page.getByRole('button', { name: 'Load' }).click();
const response = await responsePromise;
console.log('Status:', response.status());
```

> **For comprehensive waiting patterns** (navigation, element state, network, polling), see [assertions-waiting.md](../core/assertions-waiting.md#waiting-strategies).

### Debug Slow Requests

```typescript
test('find slow requests', async ({ page }) => {
	page.on('requestfinished', (request) => {
		const timing = request.timing();
		const total = timing.responseEnd - timing.requestStart;
		if (total > 1000) {
			console.log(`SLOW (${total}ms): ${request.url()}`);
		}
	});

	await page.goto('/');
});
```

## Debugging in CI

### Simulate CI Locally

```bash
# Run in headless mode like CI
CI=true npx playwright test

# Match CI browser versions
npx playwright install --with-deps

# Run in Docker (same as CI)
docker run --rm -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.40.0-jammy \
  npx playwright test
```

### CI-Specific Configuration

```typescript
// playwright.config.ts
export default defineConfig({
	// More artifacts in CI for debugging
	use: {
		trace: process.env.CI ? 'on-first-retry' : 'off',
		video: process.env.CI ? 'retain-on-failure' : 'off',
		screenshot: process.env.CI ? 'only-on-failure' : 'off'
	},

	// More retries in CI (but investigate failures!)
	retries: process.env.CI ? 2 : 0
});
```

### Debug CI Environment

```typescript
test('CI environment check', async ({ page }, testInfo) => {
	console.log('CI:', process.env.CI);
	console.log('Project:', testInfo.project.name);
	console.log('Worker:', testInfo.workerIndex);
	console.log('Retry:', testInfo.retry);
	console.log('Base URL:', testInfo.project.use.baseURL);

	// Check viewport
	const viewport = page.viewportSize();
	console.log('Viewport:', viewport);
});
```

## Debugging Authentication

```typescript
test('debug auth', async ({ page, context }) => {
	// Inspect current storage state
	const storage = await context.storageState();
	console.log(
		'Cookies:',
		storage.cookies.map((c) => c.name)
	);

	// Check if auth cookies are present
	const cookies = await context.cookies();
	const authCookie = cookies.find((c) => c.name.includes('session'));
	console.log('Auth cookie:', authCookie ? 'present' : 'MISSING');

	await page.goto('/protected');

	// Check if redirected to login (auth failed)
	if (page.url().includes('/login')) {
		console.error('Auth failed - redirected to login');
		// Save state for inspection
		await context.storageState({ path: 'debug-auth.json' });
	}
});
```

## Debugging Screenshots

### Compare Visual State

```typescript
test('visual debug', async ({ page }, testInfo) => {
	await page.goto('/');

	// Screenshot before action
	await page.screenshot({
		path: testInfo.outputPath('before.png'),
		fullPage: true
	});

	await page.getByRole('button', { name: 'Open Menu' }).click();

	// Screenshot after action
	await page.screenshot({
		path: testInfo.outputPath('after.png'),
		fullPage: true
	});

	// Attach to report
	await testInfo.attach('before', {
		path: testInfo.outputPath('before.png'),
		contentType: 'image/png'
	});
});
```

### Screenshot Specific Element

```typescript
test('element screenshot', async ({ page }) => {
	await page.goto('/');

	const element = page.getByTestId('problem-area');

	// Screenshot just the element
	await element.screenshot({ path: 'element-debug.png' });

	// Highlight element in full page screenshot
	await element.evaluate((el) => (el.style.border = '3px solid red'));
	await page.screenshot({ path: 'highlighted.png' });
});
```

## Common Issues

### Element Not Found

```typescript
// Debug: Check if element exists
console.log(await page.getByRole('button').count());

// Debug: Log all buttons
const buttons = await page.getByRole('button').all();
for (const button of buttons) {
	console.log(await button.textContent());
}

// Debug: Screenshot before action
await page.screenshot({ path: 'debug.png' });
await page.getByRole('button').click();
```

### Timeout Issues

```typescript
// Increase timeout for slow operations
await expect(page.getByText('Loaded')).toBeVisible({ timeout: 30000 });

// Global timeout increase
test.setTimeout(60000);

// Check what's blocking
test('debug timeout', async ({ page }) => {
	await page.goto('/slow-page');

	// Log network activity
	page.on('request', (request) => console.log('>>', request.url()));
	page.on('response', (response) => console.log('<<', response.url(), response.status()));
});
```

### Selector Issues

```typescript
// Debug: Highlight element
await page.getByRole('button').highlight();

// Debug: Evaluate selector in browser console
// Run in Inspector console:
// playwright.locator('button').first().highlight()

// Debug: Get element info
const element = page.getByRole('button');
console.log('Count:', await element.count());
console.log('Visible:', await element.isVisible());
console.log('Enabled:', await element.isEnabled());
```

### Frame Issues

```typescript
// Debug: List all frames
for (const frame of page.frames()) {
	console.log('Frame:', frame.url());
}

// Debug: Check if element is in iframe
const frame = page.frameLocator('iframe').first();
console.log(await frame.getByRole('button').count());
```

## Logging

### Capture Browser Console

```typescript
test('with logging', async ({ page }) => {
	page.on('console', (msg) => console.log('Browser:', msg.text()));
	page.on('pageerror', (error) => console.log('Page error:', error.message));
	await page.goto('/');
});
```

> **For comprehensive console error handling** (fail on errors, allowed patterns, fixtures), see [console-errors.md](console-errors.md).

### Custom Test Attachments

```typescript
test('with attachments', async ({ page }, testInfo) => {
	// Attach screenshot to report
	const screenshot = await page.screenshot();
	await testInfo.attach('screenshot', {
		body: screenshot,
		contentType: 'image/png'
	});

	// Attach logs or data
	await testInfo.attach('logs', {
		body: 'Custom log data',
		contentType: 'text/plain'
	});

	// Use testInfo for output paths
	const outputPath = testInfo.outputPath('debug-file.json');
});
```

## Troubleshooting Checklist

### By Symptom

| Symptom                                       | Common Causes                                                | Quick Fixes                                                         | Reference                                                                                  |
| --------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Element not found**                         | Wrong selector, element not visible, in iframe, timing issue | Check locator with Inspector, wait for visibility, use frameLocator | [locators.md](../core/locators.md), [assertions-waiting.md](../core/assertions-waiting.md) |
| **Timeout errors**                            | Slow network, heavy page load, waiting for wrong condition   | Increase timeout, wait for specific response, check network tab     | [assertions-waiting.md](../core/assertions-waiting.md)                                     |
| **Flaky tests**                               | Race conditions, shared state, timing dependencies           | See comprehensive flaky test guide                                  | [flaky-tests.md](flaky-tests.md)                                                           |
| **Tests pass locally, fail in CI**            | Environment differences, missing dependencies, timing        | Simulate CI locally, check CI logs, verify environment vars         | [ci-cd.md](../infrastructure-ci-cd/ci-cd.md), [flaky-tests.md](flaky-tests.md)             |
| **Slow test execution**                       | Not parallelized, heavy network calls, unnecessary waits     | Enable parallelization, mock APIs, optimize waits                   | [performance.md](../infrastructure-ci-cd/performance.md)                                   |
| **Selector works in browser but not in test** | Element not attached, wrong context, dynamic content         | Use auto-waiting, check iframe, verify element state                | [locators.md](../core/locators.md)                                                         |
| **Test fails on retry**                       | Non-deterministic data, external dependencies                | Use test data fixtures, mock external services                      | [fixtures-hooks.md](../core/fixtures-hooks.md)                                             |

### Step-by-Step Debugging Process

1. **Reproduce the issue**

    ```bash
    # Run with trace enabled
    npx playwright test tests/failing.spec.ts --trace on

    # If intermittent, run multiple times
    npx playwright test --repeat-each=10
    ```

2. **Inspect the failure**

    ```bash
    # View trace
    npx playwright show-trace test-results/path-to-trace.zip

    # Run in headed mode to watch
    npx playwright test --headed

    # Use inspector for step-by-step
    PWDEBUG=1 npx playwright test
    ```

3. **Isolate the problem**

    ```typescript
    // Add debugging points
    await page.pause();

    // Log element state
    console.log('Element count:', await page.getByRole('button').count());
    console.log('Element visible:', await page.getByRole('button').isVisible());

    // Take screenshot at failure point
    await page.screenshot({ path: 'debug.png' });
    ```

4. **Check related areas**
    - Network requests: Are API calls completing? (see [Debugging Network Issues](#debugging-network-issues))
    - Timing: Is auto-waiting working correctly?
    - State: Is the test isolated? (see [flaky-tests.md](flaky-tests.md))
    - Environment: Does it work locally but fail in CI? (see [Debugging in CI](#debugging-in-ci))

5. **Apply fix and verify**
    - Fix the root cause (not just symptoms)
    - Run multiple times to confirm stability: `--repeat-each=10`
    - Check related tests aren't affected

## Related References

- **Flaky tests**: See [flaky-tests.md](flaky-tests.md) for comprehensive flaky test guide
- **Locator issues**: See [locators.md](../core/locators.md) for selector strategies
- **Waiting problems**: See [assertions-waiting.md](../core/assertions-waiting.md) for waiting patterns
- **Test isolation**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for fixtures and isolation
- **CI issues**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for CI configuration
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall