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

core/annotations.md

View on GitHub
# Test Annotations & Organization

## Table of Contents

1. [Skip Annotations](#skip-annotations)
2. [Fixme & Fail Annotations](#fixme--fail-annotations)
3. [Slow Tests](#slow-tests)
4. [Test Steps](#test-steps)
5. [Custom Annotations](#custom-annotations)
6. [Conditional Annotations](#conditional-annotations)

## Skip Annotations

### Basic Skip

```typescript
// Skip unconditionally
test.skip('feature not implemented', async ({ page }) => {
	// This test won't run
});

// Skip with reason
test('payment flow', async ({ page }) => {
	test.skip(true, 'Payment gateway in maintenance');
	// Test body won't execute
});
```

### Conditional Skip

```typescript
test('webkit-specific feature', async ({ page, browserName }) => {
	test.skip(browserName !== 'webkit', 'This feature only works in WebKit');

	await page.goto('/webkit-feature');
});

test('production only', async ({ page }) => {
	test.skip(process.env.ENV !== 'production', 'Only runs against production');

	await page.goto('/prod-feature');
});
```

### Skip by Platform

```typescript
test('windows-specific', async ({ page }) => {
	test.skip(process.platform !== 'win32', 'Windows only');
});

test('not on CI', async ({ page }) => {
	test.skip(!!process.env.CI, 'Skipped in CI environment');
});
```

### Skip Describe Block

```typescript
test.describe('Admin features', () => {
	test.skip(({ browserName }) => browserName === 'firefox', 'Firefox admin bug');

	test('admin dashboard', async ({ page }) => {
		// Skipped in Firefox
	});

	test('admin settings', async ({ page }) => {
		// Skipped in Firefox
	});
});
```

## Fixme & Fail Annotations

### Fixme - Known Issues

```typescript
// Mark test as needing fix (skips the test)
test.fixme('broken after refactor', async ({ page }) => {
	// Test won't run but is tracked
});

// Conditional fixme
test('flaky on CI', async ({ page }) => {
	test.fixme(!!process.env.CI, 'Investigate CI flakiness - ticket #123');

	await page.goto('/flaky-feature');
});
```

### Fail - Expected Failures

```typescript
// Test is expected to fail (runs but expects failure)
test('known bug', async ({ page }) => {
	test.fail();

	await page.goto('/buggy-page');
	// If this passes, the test fails (bug was fixed!)
	await expect(page.getByText('Working')).toBeVisible();
});

// Conditional fail
test('fails on webkit', async ({ page, browserName }) => {
	test.fail(browserName === 'webkit', 'WebKit rendering bug #456');

	await page.goto('/render-test');
	await expect(page.getByTestId('element')).toHaveCSS('width', '100px');
});
```

### Difference Between Skip, Fixme, Fail

| Annotation     | Runs? | Use Case                         |
| -------------- | ----- | -------------------------------- |
| `test.skip()`  | No    | Feature not applicable           |
| `test.fixme()` | No    | Known bug, needs investigation   |
| `test.fail()`  | Yes   | Expected to fail, tracking a bug |

## Slow Tests

### Mark Slow Tests

```typescript
// Triple the default timeout
test('large data import', async ({ page }) => {
	test.slow();

	await page.goto('/import');
	await page.setInputFiles('#file', 'large-file.csv');
	await page.getByRole('button', { name: 'Import' }).click();

	await expect(page.getByText('Import complete')).toBeVisible();
});

// Conditional slow
test('video processing', async ({ page, browserName }) => {
	test.slow(browserName === 'webkit', 'WebKit video processing is slow');

	await page.goto('/video-editor');
});
```

### Custom Timeout

```typescript
test('very long operation', async ({ page }) => {
	// Set specific timeout (in milliseconds)
	test.setTimeout(120000); // 2 minutes

	await page.goto('/long-operation');
});

// Timeout for describe block
test.describe('Integration tests', () => {
	test.describe.configure({ timeout: 60000 });

	test('test 1', async ({ page }) => {
		// Has 60 second timeout
	});
});
```

## Test Steps

### Basic Steps

```typescript
test('checkout flow', async ({ page }) => {
	await test.step('Add item to cart', async () => {
		await page.goto('/products');
		await page.getByRole('button', { name: 'Add to Cart' }).click();
	});

	await test.step('Go to checkout', async () => {
		await page.getByRole('link', { name: 'Cart' }).click();
		await page.getByRole('button', { name: 'Checkout' }).click();
	});

	await test.step('Fill shipping info', async () => {
		await page.getByLabel('Address').fill('123 Test St');
		await page.getByLabel('City').fill('Test City');
	});

	await test.step('Complete payment', async () => {
		await page.getByLabel('Card').fill('4242424242424242');
		await page.getByRole('button', { name: 'Pay' }).click();
	});

	await expect(page.getByText('Order confirmed')).toBeVisible();
});
```

### Nested Steps

```typescript
test('user registration', async ({ page }) => {
	await test.step('Fill registration form', async () => {
		await page.goto('/register');

		await test.step('Personal info', async () => {
			await page.getByLabel('Name').fill('John Doe');
			await page.getByLabel('Email').fill('john@example.com');
		});

		await test.step('Security', async () => {
			await page.getByLabel('Password').fill('SecurePass123');
			await page.getByLabel('Confirm Password').fill('SecurePass123');
		});
	});

	await test.step('Submit and verify', async () => {
		await page.getByRole('button', { name: 'Register' }).click();
		await expect(page.getByText('Welcome')).toBeVisible();
	});
});
```

### Steps with Return Values

```typescript
test('verify order', async ({ page }) => {
	const orderId = await test.step('Create order', async () => {
		await page.goto('/checkout');
		await page.getByRole('button', { name: 'Place Order' }).click();

		// Return value from step
		return await page.getByTestId('order-id').textContent();
	});

	await test.step('Verify order details', async () => {
		await page.goto(`/orders/${orderId}`);
		await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
	});
});
```

### Step in Page Object

```typescript
// pages/checkout.page.ts
export class CheckoutPage {
	async fillShippingInfo(address: string, city: string) {
		await test.step('Fill shipping information', async () => {
			await this.page.getByLabel('Address').fill(address);
			await this.page.getByLabel('City').fill(city);
		});
	}

	async completePayment(cardNumber: string) {
		await test.step('Complete payment', async () => {
			await this.page.getByLabel('Card').fill(cardNumber);
			await this.page.getByRole('button', { name: 'Pay' }).click();
		});
	}
}
```

## Custom Annotations

### Add Annotations

```typescript
test('important feature', async ({ page }, testInfo) => {
	// Add custom annotation
	testInfo.annotations.push({
		type: 'priority',
		description: 'high'
	});

	testInfo.annotations.push({
		type: 'ticket',
		description: 'JIRA-123'
	});

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

### Annotation Fixture

```typescript
// fixtures/annotations.fixture.ts
import { test as base, TestInfo } from '@playwright/test';

type AnnotationFixtures = {
	annotate: {
		ticket: (id: string) => void;
		priority: (level: 'low' | 'medium' | 'high') => void;
		owner: (name: string) => void;
	};
};

export const test = base.extend<AnnotationFixtures>({
	annotate: async ({}, use, testInfo) => {
		await use({
			ticket: (id) => {
				testInfo.annotations.push({ type: 'ticket', description: id });
			},
			priority: (level) => {
				testInfo.annotations.push({ type: 'priority', description: level });
			},
			owner: (name) => {
				testInfo.annotations.push({ type: 'owner', description: name });
			}
		});
	}
});

// Usage
test('critical feature', async ({ page, annotate }) => {
	annotate.ticket('JIRA-456');
	annotate.priority('high');
	annotate.owner('Alice');

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

### Read Annotations in Reporter

```typescript
// reporters/annotation-reporter.ts
import { Reporter, TestCase, TestResult } from '@playwright/test/reporter';

class AnnotationReporter implements Reporter {
	onTestEnd(test: TestCase, result: TestResult) {
		const ticket = test.annotations.find((a) => a.type === 'ticket');
		const priority = test.annotations.find((a) => a.type === 'priority');

		if (ticket) {
			console.log(`Test linked to: ${ticket.description}`);
		}

		if (priority?.description === 'high' && result.status === 'failed') {
			console.log(`HIGH PRIORITY FAILURE: ${test.title}`);
		}
	}
}

export default AnnotationReporter;
```

## Conditional Annotations

### Annotation Helper

```typescript
// helpers/test-annotations.ts
import { test } from '@playwright/test';

export function skipInCI(reason = 'Skipped in CI') {
	test.skip(!!process.env.CI, reason);
}

export function skipInBrowser(browser: string, reason: string) {
	test.beforeEach(({ browserName }) => {
		test.skip(browserName === browser, reason);
	});
}

export function onlyInEnv(env: string) {
	test.skip(process.env.ENV !== env, `Only runs in ${env}`);
}
```

```typescript
// tests/feature.spec.ts
import { skipInCI, onlyInEnv } from '../helpers/test-annotations';

test('local only feature', async ({ page }) => {
	skipInCI('Uses local resources');

	await page.goto('/local-feature');
});

test('production check', async ({ page }) => {
	onlyInEnv('production');

	await page.goto('/prod-only');
});
```

### Describe-Level Conditions

```typescript
test.describe('Mobile features', () => {
	test.beforeEach(({ isMobile }) => {
		test.skip(!isMobile, 'Mobile only tests');
	});

	test('touch gestures', async ({ page }) => {
		// Only runs on mobile
	});
});

test.describe('Desktop features', () => {
	test.beforeEach(({ isMobile }) => {
		test.skip(isMobile, 'Desktop only tests');
	});

	test('hover interactions', async ({ page }) => {
		// Only runs on desktop
	});
});
```

## Anti-Patterns to Avoid

| Anti-Pattern                | Problem                | Solution                         |
| --------------------------- | ---------------------- | -------------------------------- |
| Skipping without reason     | Hard to track why      | Always provide description       |
| Too many skipped tests      | Test debt accumulates  | Review and clean up regularly    |
| Using skip instead of fixme | Loses intent           | Use fixme for bugs, skip for N/A |
| Not using steps             | Hard to debug failures | Group logical actions in steps   |

## Related References

- **Test Tags**: See [test-tags.md](test-tags.md) for tagging and filtering tests with `--grep`
- **Test Organization**: See [test-suite-structure.md](test-suite-structure.md) for structuring tests
- **Debugging**: See [debugging.md](../debugging/debugging.md) for troubleshooting
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