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

testing-patterns/api-testing.md

View on GitHub
# API Testing

## Table of Contents

1. [Patterns](#patterns)
2. [Decision Guide](#decision-guide)
3. [Anti-Patterns](#anti-patterns)
4. [Troubleshooting](#troubleshooting)

> **When to use**: Testing REST APIs directly — validating endpoints, seeding test data, or verifying backend behavior without browser overhead.
> **See also**: [graphql-testing.md](graphql-testing.md) for GraphQL-specific patterns.

## Patterns

### Request Fixtures for Authenticated Clients

**Use when**: Multiple tests need an authenticated API client with shared configuration.
**Avoid when**: A single test makes one-off API calls — use the built-in `request` fixture directly.

```typescript
// fixtures/api-fixtures.ts
import { test as base, expect, APIRequestContext } from '@playwright/test';

type ApiFixtures = {
	authApi: APIRequestContext;
	adminApi: APIRequestContext;
};

export const test = base.extend<ApiFixtures>({
	authApi: async ({ playwright }, use) => {
		const ctx = await playwright.request.newContext({
			baseURL: 'https://api.myapp.io',
			extraHTTPHeaders: {
				Authorization: `Bearer ${process.env.API_TOKEN}`,
				Accept: 'application/json'
			}
		});
		await use(ctx);
		await ctx.dispose();
	},

	adminApi: async ({ playwright }, use) => {
		const loginCtx = await playwright.request.newContext({
			baseURL: 'https://api.myapp.io'
		});
		const loginResp = await loginCtx.post('/auth/login', {
			data: {
				email: process.env.ADMIN_EMAIL,
				password: process.env.ADMIN_PASSWORD
			}
		});
		expect(loginResp.ok()).toBeTruthy();
		const { token } = await loginResp.json();
		await loginCtx.dispose();

		const ctx = await playwright.request.newContext({
			baseURL: 'https://api.myapp.io',
			extraHTTPHeaders: {
				Authorization: `Bearer ${token}`,
				Accept: 'application/json'
			}
		});
		await use(ctx);
		await ctx.dispose();
	}
});

export { expect };
```

```typescript
// tests/api/admin.spec.ts
import { test, expect } from '../../fixtures/api-fixtures';

test('admin retrieves all accounts', async ({ adminApi }) => {
	const resp = await adminApi.get('/admin/accounts');
	expect(resp.status()).toBe(200);
	const body = await resp.json();
	expect(body.accounts.length).toBeGreaterThan(0);
});
```

### CRUD Operations

**Use when**: Making HTTP requests — GET, POST, PUT, PATCH, DELETE with headers, query params, and bodies.
**Avoid when**: You need to test browser-rendered responses (redirects, cookies with `HttpOnly`).

```typescript
import { test, expect } from '@playwright/test';

test('full CRUD cycle', async ({ request }) => {
	// GET with query params
	const listResp = await request.get('/api/items', {
		params: { page: 1, limit: 10, category: 'tools' }
	});
	expect(listResp.ok()).toBeTruthy();

	// POST with JSON body
	const createResp = await request.post('/api/items', {
		data: {
			title: 'Hammer',
			price: 19.99,
			category: 'tools'
		}
	});
	expect(createResp.status()).toBe(201);
	const created = await createResp.json();

	// PUT — full replacement
	const putResp = await request.put(`/api/items/${created.id}`, {
		data: {
			title: 'Claw Hammer',
			price: 24.99,
			category: 'tools'
		}
	});
	expect(putResp.ok()).toBeTruthy();

	// PATCH — partial update
	const patchResp = await request.patch(`/api/items/${created.id}`, {
		data: { price: 22.5 }
	});
	expect(patchResp.ok()).toBeTruthy();
	const patched = await patchResp.json();
	expect(patched.price).toBe(22.5);

	// DELETE
	const delResp = await request.delete(`/api/items/${created.id}`);
	expect(delResp.status()).toBe(204);

	// Verify deletion
	const getDeleted = await request.get(`/api/items/${created.id}`);
	expect(getDeleted.status()).toBe(404);
});

test('form-urlencoded body', async ({ request }) => {
	const resp = await request.post('/oauth/token', {
		form: {
			grant_type: 'client_credentials',
			client_id: 'my-client',
			client_secret: 'secret-value'
		}
	});
	expect(resp.ok()).toBeTruthy();
	const token = await resp.json();
	expect(token).toHaveProperty('access_token');
});
```

### Dedicated API Project Configuration

**Use when**: Writing dedicated API test suites that do not need a browser.

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
	projects: [
		{
			name: 'api',
			testDir: './tests/api',
			use: {
				baseURL: 'https://api.myapp.io',
				extraHTTPHeaders: { Accept: 'application/json' }
			}
		},
		{
			name: 'e2e',
			testDir: './tests/e2e',
			use: {
				baseURL: 'https://myapp.io',
				browserName: 'chromium'
			}
		}
	]
});
```

### Response Assertions

**Use when**: Validating response status, headers, and body structure.
**Avoid when**: Never skip these — every API test should assert on status and body.

```typescript
import { test, expect } from '@playwright/test';

test('comprehensive response validation', async ({ request }) => {
	const resp = await request.get('/api/items/101');

	// Status code — always check first
	expect(resp.status()).toBe(200);
	expect(resp.ok()).toBeTruthy();

	// Headers
	expect(resp.headers()['content-type']).toContain('application/json');
	expect(resp.headers()['cache-control']).toMatch(/max-age=\d+/);

	const item = await resp.json();

	// Exact match on known fields
	expect(item.id).toBe(101);
	expect(item.title).toBe('Widget');

	// Partial match — ignore fields you don't care about
	expect(item).toMatchObject({
		id: 101,
		title: 'Widget',
		status: expect.stringMatching(/^(active|inactive|archived)$/)
	});

	// Type checks
	expect(item).toMatchObject({
		id: expect.any(Number),
		title: expect.any(String),
		createdAt: expect.any(String),
		tags: expect.any(Array)
	});

	// Array content
	expect(item.tags).toEqual(expect.arrayContaining(['featured']));
	expect(item.tags).not.toContain('deprecated');

	// Nested object
	expect(item.metadata).toMatchObject({
		views: expect.any(Number),
		rating: expect.any(Number)
	});

	// Date format
	expect(new Date(item.createdAt).toISOString()).toBe(item.createdAt);
});

test('list response structure', async ({ request }) => {
	const resp = await request.get('/api/items');
	const body = await resp.json();

	expect(body.items).toHaveLength(10);

	for (const item of body.items) {
		expect(item).toMatchObject({
			id: expect.any(Number),
			title: expect.any(String),
			price: expect.any(Number)
		});
	}

	expect(body.pagination).toEqual({
		page: 1,
		limit: 10,
		total: expect.any(Number),
		totalPages: expect.any(Number)
	});
});
```

### API Data Seeding

**Use when**: E2E tests need specific data to exist before running. API seeding is 10-100x faster than UI-based setup.
**Avoid when**: The test specifically validates the creation flow through the UI.

```typescript
import { test as base, expect } from '@playwright/test';

type SeedFixtures = {
	seedAccount: { id: number; email: string; password: string };
	seedWorkspace: { id: number; name: string };
};

export const test = base.extend<SeedFixtures>({
	seedAccount: async ({ request }, use) => {
		const email = `account-${Date.now()}@test.io`;
		const password = 'SecurePass123!';

		const resp = await request.post('/api/accounts', {
			data: { name: 'Test Account', email, password }
		});
		expect(resp.ok()).toBeTruthy();
		const account = await resp.json();

		await use({ id: account.id, email, password });

		// Cleanup
		await request.delete(`/api/accounts/${account.id}`);
	},

	seedWorkspace: async ({ request, seedAccount }, use) => {
		const resp = await request.post('/api/workspaces', {
			data: { name: `Workspace ${Date.now()}`, ownerId: seedAccount.id }
		});
		expect(resp.ok()).toBeTruthy();
		const workspace = await resp.json();

		await use({ id: workspace.id, name: workspace.name });

		await request.delete(`/api/workspaces/${workspace.id}`);
	}
});

export { expect };
```

```typescript
// tests/e2e/workspace-dashboard.spec.ts
import { test, expect } from '../../fixtures/seed-fixtures';

test('user sees workspace on dashboard', async ({ page, seedAccount, seedWorkspace }) => {
	await page.goto('/login');
	await page.getByLabel('Email').fill(seedAccount.email);
	await page.getByLabel('Password').fill(seedAccount.password);
	await page.getByRole('button', { name: 'Sign in' }).click();

	await page.waitForURL('/dashboard');
	await expect(page.getByRole('heading', { name: seedWorkspace.name })).toBeVisible();
});
```

### Error Response Testing

**Use when**: Every API has error paths — test them. A missing 401 test today is a security hole tomorrow.

```typescript
import { test, expect } from '@playwright/test';

test.describe('Error responses', () => {
	test('400 — validation error with details', async ({ request }) => {
		const resp = await request.post('/api/items', {
			data: { title: '', price: -5 }
		});
		expect(resp.status()).toBe(400);

		const body = await resp.json();
		expect(body).toMatchObject({
			error: 'Validation Error',
			details: expect.any(Array)
		});
		expect(body.details).toEqual(
			expect.arrayContaining([
				expect.objectContaining({
					field: 'title',
					message: expect.any(String)
				}),
				expect.objectContaining({
					field: 'price',
					message: expect.any(String)
				})
			])
		);
	});

	test('401 — missing authentication', async ({ request }) => {
		const resp = await request.get('/api/protected/resource', {
			headers: { Authorization: '' }
		});
		expect(resp.status()).toBe(401);
		const body = await resp.json();
		expect(body.error).toMatch(/unauthorized|unauthenticated/i);
	});

	test('403 — insufficient permissions', async ({ request }) => {
		const resp = await request.delete('/api/admin/items/1');
		expect(resp.status()).toBe(403);
		const body = await resp.json();
		expect(body.error).toMatch(/forbidden|insufficient permissions/i);
	});

	test('404 — resource not found', async ({ request }) => {
		const resp = await request.get('/api/items/999999');
		expect(resp.status()).toBe(404);
		const body = await resp.json();
		expect(body).toMatchObject({ error: expect.stringMatching(/not found/i) });
	});

	test('409 — conflict on duplicate', async ({ request }) => {
		const sku = `SKU-${Date.now()}`;
		await request.post('/api/items', { data: { title: 'First', sku } });

		const resp = await request.post('/api/items', {
			data: { title: 'Duplicate', sku }
		});
		expect(resp.status()).toBe(409);
	});

	test('422 — unprocessable entity', async ({ request }) => {
		const resp = await request.post('/api/orders', {
			data: { items: [] }
		});
		expect(resp.status()).toBe(422);
		const body = await resp.json();
		expect(body.error).toContain('at least one item');
	});

	test('429 — rate limiting', async ({ request }) => {
		const responses = await Promise.all(
			Array.from({ length: 50 }, () => request.get('/api/search', { params: { q: 'test' } }))
		);
		const rateLimited = responses.filter((r) => r.status() === 429);
		expect(rateLimited.length).toBeGreaterThan(0);
		expect(rateLimited[0].headers()['retry-after']).toBeDefined();
	});
});
```

### File Upload via API

**Use when**: Testing file upload endpoints with multipart form data.
**Avoid when**: You need to test the browser file picker dialog — use `page.setInputFiles()` instead.

```typescript
import { test, expect } from '@playwright/test';
import path from 'path';
import fs from 'fs';

test('upload file via multipart', async ({ request }) => {
	const filePath = path.resolve('tests/fixtures/report.pdf');

	const resp = await request.post('/api/documents/upload', {
		multipart: {
			file: {
				name: 'report.pdf',
				mimeType: 'application/pdf',
				buffer: fs.readFileSync(filePath)
			},
			description: 'Monthly report',
			category: 'reports'
		}
	});

	expect(resp.status()).toBe(201);
	const body = await resp.json();
	expect(body).toMatchObject({
		id: expect.any(String),
		filename: 'report.pdf',
		mimeType: 'application/pdf',
		size: expect.any(Number),
		url: expect.stringMatching(/^https:\/\//)
	});
});

test('rejects oversized files', async ({ request }) => {
	const largeBuffer = Buffer.alloc(11 * 1024 * 1024); // 11MB

	const resp = await request.post('/api/documents/upload', {
		multipart: {
			file: {
				name: 'large-file.bin',
				mimeType: 'application/octet-stream',
				buffer: largeBuffer
			}
		}
	});

	expect(resp.status()).toBe(413);
});
```

### Chained API Calls

**Use when**: Testing multi-step workflows — create, read, update, delete sequences; order flows; state machine transitions.
**Avoid when**: You can test each endpoint in isolation and the interactions are trivial.

```typescript
import { test, expect } from '@playwright/test';

test('complete order workflow', async ({ request }) => {
	// Step 1: Create a product
	const productResp = await request.post('/api/products', {
		data: { name: 'Gadget', price: 49.99, stock: 50 }
	});
	expect(productResp.status()).toBe(201);
	const product = await productResp.json();

	// Step 2: Create a cart
	const cartResp = await request.post('/api/carts', {
		data: { items: [{ productId: product.id, quantity: 3 }] }
	});
	expect(cartResp.status()).toBe(201);
	const cart = await cartResp.json();
	expect(cart.total).toBe(149.97);

	// Step 3: Checkout
	const orderResp = await request.post('/api/orders', {
		data: {
			cartId: cart.id,
			shippingAddress: {
				street: '456 Main Ave',
				city: 'Metropolis',
				zip: '54321'
			}
		}
	});
	expect(orderResp.status()).toBe(201);
	const order = await orderResp.json();
	expect(order.status).toBe('pending');
	expect(order.items).toHaveLength(1);

	// Step 4: Verify order in list
	const ordersResp = await request.get('/api/orders');
	const orders = await ordersResp.json();
	expect(orders.items.map((o: any) => o.id)).toContain(order.id);

	// Step 5: Verify stock decreased
	const updatedProduct = await (await request.get(`/api/products/${product.id}`)).json();
	expect(updatedProduct.stock).toBe(47);

	// Cleanup
	await request.delete(`/api/orders/${order.id}`);
	await request.delete(`/api/products/${product.id}`);
});

test('state machine transitions — publish workflow', async ({ request }) => {
	const createResp = await request.post('/api/articles', {
		data: { title: 'Draft Article', body: 'Content here.' }
	});
	const article = await createResp.json();
	expect(article.status).toBe('draft');

	// Submit for review
	const reviewResp = await request.patch(`/api/articles/${article.id}/status`, {
		data: { status: 'in_review' }
	});
	expect(reviewResp.ok()).toBeTruthy();
	expect((await reviewResp.json()).status).toBe('in_review');

	// Approve
	const approveResp = await request.patch(`/api/articles/${article.id}/status`, {
		data: { status: 'published' }
	});
	expect(approveResp.ok()).toBeTruthy();
	expect((await approveResp.json()).status).toBe('published');

	// Cannot revert to draft from published
	const revertResp = await request.patch(`/api/articles/${article.id}/status`, {
		data: { status: 'draft' }
	});
	expect(revertResp.status()).toBe(422);

	await request.delete(`/api/articles/${article.id}`);
});

test('API + E2E hybrid — seed via API, verify in browser', async ({ request, page }) => {
	const resp = await request.post('/api/products', {
		data: {
			name: `Hybrid Product ${Date.now()}`,
			price: 35.0,
			published: true
		}
	});
	const product = await resp.json();

	await page.goto('/products');
	await expect(page.getByRole('heading', { name: product.name })).toBeVisible();
	await expect(page.getByText('$35.00')).toBeVisible();

	await request.delete(`/api/products/${product.id}`);
});
```

### Schema Validation with Zod

**Use when**: Verifying API responses match a contract — field types, required fields, value constraints.
**Avoid when**: You only need to check one or two specific fields — use `toMatchObject` instead.

```typescript
import { test, expect } from '@playwright/test';
import { z } from 'zod';

const ItemSchema = z.object({
	id: z.number().positive(),
	title: z.string().min(1),
	price: z.number().nonnegative(),
	status: z.enum(['active', 'inactive', 'archived']),
	createdAt: z.string().datetime(),
	metadata: z.object({
		views: z.number().int().nonnegative(),
		rating: z.number().min(0).max(5).nullable()
	})
});

const PaginatedItemsSchema = z.object({
	items: z.array(ItemSchema),
	pagination: z.object({
		page: z.number().int().positive(),
		limit: z.number().int().positive(),
		total: z.number().int().nonnegative()
	})
});

test('GET /api/items matches schema', async ({ request }) => {
	const resp = await request.get('/api/items');
	expect(resp.ok()).toBeTruthy();

	const body = await resp.json();
	const result = PaginatedItemsSchema.safeParse(body);

	if (!result.success) {
		throw new Error(
			`Schema validation failed:\n${result.error.issues
				.map((i) => `  ${i.path.join('.')}: ${i.message}`)
				.join('\n')}`
		);
	}
});
```

## Decision Guide

| Scenario                                         | Use API Tests               | Use E2E Tests                  | Why                                                                |
| ------------------------------------------------ | --------------------------- | ------------------------------ | ------------------------------------------------------------------ |
| Validate response status/body/headers            | Yes                         | No                             | No browser needed; 10-100x faster                                  |
| Test business logic (calculations, rules)        | Yes                         | No                             | API tests isolate backend logic from UI                            |
| Verify form submission creates correct data      | Seed via API, submit via UI | Yes                            | UI test validates the form; API check confirms persistence         |
| Test error messages shown to user                | No                          | Yes                            | Error rendering is a UI concern                                    |
| Validate pagination, filtering, sorting          | Yes                         | Maybe both                     | API test for correctness; E2E test only if the UI logic is complex |
| Seed test data for E2E tests                     | Yes (fixture)               | No                             | API seeding is fast and reliable                                   |
| Test auth flows (login/logout/RBAC)              | Yes for token/session logic | Yes for UI flow                | Both matter: API protects resources, UI guides users               |
| Verify file upload processing                    | Yes                         | Only if testing file picker UI | API test validates backend processing                              |
| Contract/schema regression testing               | Yes                         | No                             | Schema tests run in milliseconds                                   |
| Test third-party webhook handling                | Yes                         | No                             | Webhooks are API-to-API; no UI involved                            |
| Verify redirect behavior after action            | No                          | Yes                            | Redirects are browser/navigation concerns                          |
| Test real-time updates (WebSocket + API trigger) | API triggers                | E2E verifies                   | Seed via API, observe in browser                                   |

## Anti-Patterns

| Don't Do This                                        | Problem                                                                                | Do This Instead                                                   |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Use E2E tests to validate pure API responses         | Slow, flaky, launches a browser for no reason                                          | Use `request` fixture — no browser, direct HTTP                   |
| Ignore `response.status()`                           | A 500 with a fallback body can pass all body assertions                                | Always assert status first: `expect(response.status()).toBe(200)` |
| Skip response header checks                          | Missing `Content-Type`, `Cache-Control`, CORS headers cause production bugs            | Assert critical headers                                           |
| Only test the happy path                             | Real users trigger 400, 401, 403, 404, 409, 422 — every one needs a test               | Dedicate a `describe` block to error responses                    |
| Hardcode IDs in API tests                            | Tests break when database is reset or IDs are reassigned                               | Create resources in the test, use returned IDs                    |
| Share mutable state between tests                    | Tests that depend on execution order are flaky and cannot run in parallel              | Each test creates and cleans up its own data                      |
| Parse `response.text()` then `JSON.parse()` manually | Playwright's `response.json()` handles this and throws clear errors on non-JSON        | Use `await response.json()`                                       |
| Forget cleanup after creating resources              | Test pollution: subsequent tests may see stale data or hit unique constraints          | Use fixtures with teardown or explicit `delete` calls             |
| Use `page.request` when you don't need a page        | `page.request` shares cookies with the browser context, which may cause auth confusion | Use the standalone `request` fixture for pure API tests           |

## Troubleshooting

### "Request failed: connect ECONNREFUSED 127.0.0.1:3000"

**Cause**: The API server is not running, or `baseURL` points to the wrong host/port.

**Fix**: Verify the server is running before tests. Use `webServer` in config to start it automatically.

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

### "response.json() failed — body is not valid JSON"

**Cause**: The endpoint returned HTML (error page), plain text, or an empty body instead of JSON.

**Fix**: Check `response.status()` first — a 500 or 302 often returns HTML. Log `await response.text()` to see the actual body. Verify the `Accept: application/json` header is set.

```typescript
const resp = await request.get('/api/endpoint');
if (!resp.ok()) {
	console.error(`Status: ${resp.status()}, Body: ${await resp.text()}`);
}
const body = await resp.json();
```

### "401 Unauthorized" when using `request` fixture

**Cause**: The built-in `request` fixture does not carry browser cookies or auth tokens automatically.

**Fix**: Set `extraHTTPHeaders` in config or create a custom authenticated fixture. If you need cookies from a browser login, use `page.request` instead.

```typescript
// Option A: config-level headers
export default defineConfig({
	use: {
		extraHTTPHeaders: { Authorization: `Bearer ${process.env.API_TOKEN}` }
	}
});

// Option B: per-request headers
const resp = await request.get('/api/resource', {
	headers: { Authorization: `Bearer ${token}` }
});

// Option C: use page.request to inherit browser cookies
test('API call with browser auth', async ({ page }) => {
	await page.goto('/login');
	// ... login via UI ...
	const resp = await page.request.get('/api/profile');
	expect(resp.ok()).toBeTruthy();
});
```

### Tests pass locally but fail in CI

**Cause**: Different environments, database state, or missing environment variables.

**Fix**: Use `process.env` for secrets and base URLs. Run database seeds or migrations in `globalSetup`. Use unique identifiers (timestamps, UUIDs) for test data. Check that the CI `baseURL` matches the deployed service.
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