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

architecture/when-to-mock.md

View on GitHub
# Mocking Strategy: Real vs Mock Services

## Table of Contents

1. [Core Principle](#core-principle)
2. [Decision Matrix](#decision-matrix)
3. [Decision Flowchart](#decision-flowchart)
4. [Mocking Techniques](#mocking-techniques)
5. [Real Service Strategies](#real-service-strategies)
6. [Hybrid Approach: Fixture-Based Mock Control](#hybrid-approach-fixture-based-mock-control)
7. [Validating Mock Accuracy](#validating-mock-accuracy)
8. [Anti-Patterns](#anti-patterns)

> **When to use**: Deciding whether to mock API calls, intercept network requests, or hit real services in Playwright tests.

## Core Principle

**Mock at the boundary, test your stack end-to-end.** Mock third-party services you don't own (payment gateways, email providers, OAuth). Never mock your own frontend-to-backend communication. Tests should prove YOUR code works, not that third-party APIs are available.

## Decision Matrix

| Scenario                          | Mock?                    | Strategy                                        |
| --------------------------------- | ------------------------ | ----------------------------------------------- |
| Your own REST/GraphQL API         | Never                    | Hit real API against staging or local dev       |
| Your database (through your API)  | Never                    | Seed via API or fixtures                        |
| Authentication (your auth system) | Mostly no                | Use `storageState` to skip login in most tests  |
| Stripe / payment gateway          | Always                   | `route.fulfill()` with expected responses       |
| SendGrid / email service          | Always                   | Mock the API call, verify request payload       |
| OAuth providers (Google, GitHub)  | Always                   | Mock token exchange, test your callback handler |
| Analytics (Segment, Mixpanel)     | Always                   | `route.abort()` or `route.fulfill()`            |
| Maps / geocoding APIs             | Always                   | Mock with static responses                      |
| Feature flags (LaunchDarkly)      | Usually                  | Mock to force specific flag states              |
| CDN / static assets               | Never                    | Let them load normally                          |
| Flaky external dependency         | CI: mock, local: real    | Conditional mocking based on environment        |
| Slow external dependency          | Dev: mock, nightly: real | Separate test projects in config                |

## Decision Flowchart

```text
Is this service part of YOUR codebase?
├── YES → Do NOT mock. Test the real integration.
│   ├── Is it slow? → Optimize the service, not the test.
│   └── Is it flaky? → Fix the service. Flaky infra is a bug.
└── NO → It's a third-party service.
    ├── Is it paid per call? → ALWAYS mock.
    ├── Is it rate-limited? → ALWAYS mock.
    ├── Is it slow or unreliable? → ALWAYS mock.
    └── Is it a complex multi-step flow? → Mock with HAR recording.
```

## Mocking Techniques

### Blocking Unwanted Requests

Block third-party scripts that slow tests and add no coverage:

```typescript
test.beforeEach(async ({ page }) => {
	await page.route('**/{analytics,tracking,segment,hotjar}.{com,io}/**', (route) => {
		route.abort();
	});
});

test('dashboard renders without tracking scripts', async ({ page }) => {
	await page.goto('/dashboard');
	await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});
```

### Full Mock (route.fulfill)

Completely replace a third-party API response:

```typescript
test('order flow with mocked payment service', async ({ page }) => {
	await page.route('**/api/charge', (route) => {
		route.fulfill({
			status: 200,
			contentType: 'application/json',
			body: JSON.stringify({
				transactionId: 'txn_mock_abc',
				status: 'completed'
			})
		});
	});

	await page.goto('/order/confirm');
	await page.getByRole('button', { name: 'Complete Purchase' }).click();
	await expect(page.getByText('Order confirmed')).toBeVisible();
});

test('display error on payment decline', async ({ page }) => {
	await page.route('**/api/charge', (route) => {
		route.fulfill({
			status: 402,
			contentType: 'application/json',
			body: JSON.stringify({
				error: { code: 'insufficient_funds', message: 'Card declined.' }
			})
		});
	});

	await page.goto('/order/confirm');
	await page.getByRole('button', { name: 'Complete Purchase' }).click();
	await expect(page.getByRole('alert')).toContainText('Card declined');
});
```

### Partial Mock (Modify Responses)

Let the real API call happen but tweak the response:

```typescript
test('display low inventory warning', async ({ page }) => {
	await page.route('**/api/inventory/*', async (route) => {
		const response = await route.fetch();
		const data = await response.json();

		data.quantity = 1;
		data.lowStock = true;

		await route.fulfill({
			response,
			body: JSON.stringify(data)
		});
	});

	await page.goto('/products/widget-pro');
	await expect(page.getByText('Only 1 remaining')).toBeVisible();
});

test('inject test notification into real response', async ({ page }) => {
	await page.route('**/api/alerts', async (route) => {
		const response = await route.fetch();
		const data = await response.json();

		data.items.push({
			id: 'test-alert',
			text: 'Report generated',
			category: 'info'
		});

		await route.fulfill({
			response,
			body: JSON.stringify(data)
		});
	});

	await page.goto('/home');
	await expect(page.getByText('Report generated')).toBeVisible();
});
```

### Record and Replay (HAR Files)

For complex API sequences (OAuth flows, multi-step wizards):

**Recording:**

```typescript
test('capture API traffic for admin panel', async ({ page }) => {
	await page.routeFromHAR('tests/fixtures/admin-panel.har', {
		url: '**/api/**',
		update: true
	});

	await page.goto('/admin');
	await page.getByRole('tab', { name: 'Reports' }).click();
	await page.getByRole('tab', { name: 'Settings' }).click();
});
```

**Replaying:**

```typescript
test('admin panel loads with recorded data', async ({ page }) => {
	await page.routeFromHAR('tests/fixtures/admin-panel.har', {
		url: '**/api/**',
		update: false
	});

	await page.goto('/admin');
	await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible();
});
```

**HAR maintenance:**

- Record against a known-good staging environment
- Commit `.har` files to version control
- Re-record when APIs change
- Scope HAR to specific URL patterns

## Real Service Strategies

### Local Dev Server

```typescript
// playwright.config.ts
export default defineConfig({
	webServer: {
		command: 'npm run dev',
		url: 'http://localhost:3000',
		reuseExistingServer: !process.env.CI,
		timeout: 30_000
	},
	use: {
		baseURL: 'http://localhost:3000'
	}
});
```

### Staging Environment

```typescript
// playwright.config.ts
export default defineConfig({
	use: {
		baseURL: process.env.CI ? 'https://staging.example.com' : 'http://localhost:3000'
	}
});
```

### Test Containers

```typescript
// playwright.config.ts
export default defineConfig({
	webServer: {
		command: 'docker compose -f docker-compose.test.yml up --wait',
		url: 'http://localhost:3000/health',
		reuseExistingServer: !process.env.CI,
		timeout: 120_000
	},
	globalTeardown: './tests/global-teardown.ts'
});
```

```typescript
// tests/global-teardown.ts
import { execSync } from 'child_process';

export default function globalTeardown() {
	if (process.env.CI) {
		execSync('docker compose -f docker-compose.test.yml down -v');
	}
}
```

## Hybrid Approach: Fixture-Based Mock Control

Create fixtures that let individual tests opt into mocking specific services:

```typescript
// tests/fixtures/service-mocks.ts
import { test as base } from '@playwright/test';

type MockConfig = {
	mockPayments: boolean;
	mockNotifications: boolean;
	mockAnalytics: boolean;
};

export const test = base.extend<MockConfig>({
	mockPayments: [true, { option: true }],
	mockNotifications: [true, { option: true }],
	mockAnalytics: [true, { option: true }],

	page: async ({ page, mockPayments, mockNotifications, mockAnalytics }, use) => {
		if (mockPayments) {
			await page.route('**/api/billing/**', (route) => {
				route.fulfill({
					status: 200,
					contentType: 'application/json',
					body: JSON.stringify({ status: 'paid', id: 'inv_mock_789' })
				});
			});
		}

		if (mockNotifications) {
			await page.route('**/api/notify', (route) => {
				route.fulfill({
					status: 200,
					contentType: 'application/json',
					body: JSON.stringify({ delivered: true })
				});
			});
		}

		if (mockAnalytics) {
			await page.route('**/{segment,mixpanel,amplitude}.**/**', (route) => {
				route.abort();
			});
		}

		await use(page);
	}
});

export { expect } from '@playwright/test';
```

```typescript
// tests/billing.spec.ts
import { test, expect } from './fixtures/service-mocks';

test('subscription renewal sends notification', async ({ page }) => {
	await page.goto('/account/billing');
	await page.getByRole('button', { name: 'Renew Now' }).click();
	await expect(page.getByText('Subscription renewed')).toBeVisible();
});

test.describe('integration suite', () => {
	test.use({ mockPayments: false });

	test('real billing flow against test gateway', async ({ page }) => {
		await page.goto('/account/billing');
		await page.getByRole('button', { name: 'Renew Now' }).click();
		await expect(page.getByText('Subscription renewed')).toBeVisible();
	});
});
```

### Environment-Based Test Projects

```typescript
// playwright.config.ts
export default defineConfig({
	projects: [
		{
			name: 'ci-fast',
			testMatch: '**/*.spec.ts',
			use: { baseURL: 'http://localhost:3000' }
		},
		{
			name: 'nightly-full',
			testMatch: '**/*.integration.spec.ts',
			use: { baseURL: 'https://staging.example.com' },
			timeout: 120_000
		}
	]
});
```

## Validating Mock Accuracy

Guard against mock drift from real APIs:

```typescript
test.describe('contract validation', () => {
	test('billing mock matches real API shape', async ({ request }) => {
		const realResponse = await request.post('/api/billing/charge', {
			data: { amount: 5000, currency: 'usd' }
		});
		const realBody = await realResponse.json();

		const mockBody = {
			status: 'paid',
			id: 'inv_mock_789'
		};

		expect(Object.keys(mockBody).sort()).toEqual(Object.keys(realBody).sort());

		for (const key of Object.keys(mockBody)) {
			expect(typeof mockBody[key]).toBe(typeof realBody[key]);
		}
	});
});
```

## Anti-Patterns

| Don't Do This                             | Problem                                                       | Do This Instead                                               |
| ----------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| Mock your own API                         | Tests pass, app breaks. Zero integration coverage.            | Hit your real API. Mock only third-party services.            |
| Mock everything for speed                 | You test a fiction. Frontend and backend may be incompatible. | Mock only external boundaries.                                |
| Never mock anything                       | Tests are slow, flaky, fail when third parties have outages.  | Mock third-party services.                                    |
| Use outdated mocks                        | Mock returns different shape than real API.                   | Run contract validation tests. Re-record HAR files regularly. |
| Mock with `page.evaluate()` to stub fetch | Fragile, doesn't survive navigation.                          | Use `page.route()` which intercepts at network layer.         |
| Copy-paste mocks across files             | One API change requires updating many files.                  | Centralize mocks in fixtures.                                 |
| Block all network and whitelist           | Extremely brittle. Every new endpoint requires update.        | Allow all by default. Selectively mock third-party services.  |
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: 472kUpdated 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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated 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