ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse 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.
core/test-data.md
View on GitHub# Test Data Factories & Generators
This file covers **reusable test data builders** (factories, Faker, data generators). For related topics:
- **Per-test database fixtures** (isolation, transaction rollback): See [fixtures-hooks.md](fixtures-hooks.md#database-fixtures)
- **One-time database setup** (migrations, snapshots): See [global-setup.md](global-setup.md#database-patterns)
## Table of Contents
1. [Factory Pattern](#factory-pattern)
2. [Faker Integration](#faker-integration)
3. [Data-Driven Testing](#data-driven-testing)
4. [Test Data Fixtures](#test-data-fixtures)
5. [Database Seeding](#database-seeding)
## Factory Pattern
### Basic Factory
```typescript
// factories/user.factory.ts
interface User {
id: string;
email: string;
name: string;
role: 'admin' | 'user' | 'guest';
createdAt: Date;
}
let userIdCounter = 0;
export function createUser(overrides: Partial<User> = {}): User {
userIdCounter++;
return {
id: `user-${userIdCounter}`,
email: `user${userIdCounter}@test.com`,
name: `Test User ${userIdCounter}`,
role: 'user',
createdAt: new Date(),
...overrides
};
}
// Usage
const user = createUser();
const admin = createUser({ role: 'admin', name: 'Admin User' });
```
### Factory with Traits
```typescript
// factories/product.factory.ts
interface Product {
id: string;
name: string;
price: number;
stock: number;
category: string;
featured: boolean;
}
type ProductTrait = 'outOfStock' | 'featured' | 'expensive' | 'sale';
const traits: Record<ProductTrait, Partial<Product>> = {
outOfStock: { stock: 0 },
featured: { featured: true },
expensive: { price: 999.99 },
sale: { price: 9.99 }
};
let productIdCounter = 0;
export function createProduct(overrides: Partial<Product> = {}, ...traitNames: ProductTrait[]): Product {
productIdCounter++;
const appliedTraits = traitNames.reduce((acc, trait) => ({ ...acc, ...traits[trait] }), {});
return {
id: `prod-${productIdCounter}`,
name: `Product ${productIdCounter}`,
price: 29.99,
stock: 100,
category: 'General',
featured: false,
...appliedTraits,
...overrides
};
}
// Usage
const product = createProduct();
const featuredProduct = createProduct({}, 'featured');
const saleItem = createProduct({ name: 'Sale Item' }, 'sale', 'featured');
const soldOut = createProduct({}, 'outOfStock');
```
### Factory with Relationships
```typescript
// factories/order.factory.ts
import { createUser, User } from './user.factory';
import { createProduct, Product } from './product.factory';
interface OrderItem {
product: Product;
quantity: number;
}
interface Order {
id: string;
user: User;
items: OrderItem[];
total: number;
status: 'pending' | 'paid' | 'shipped' | 'delivered';
}
let orderIdCounter = 0;
export function createOrder(overrides: Partial<Order> = {}): Order {
orderIdCounter++;
const user = overrides.user ?? createUser();
const items = overrides.items ?? [{ product: createProduct(), quantity: 1 }];
const total = items.reduce((sum, item) => sum + item.product.price * item.quantity, 0);
return {
id: `order-${orderIdCounter}`,
user,
items,
total,
status: 'pending',
...overrides
};
}
// Usage
const order = createOrder();
const bigOrder = createOrder({
items: [
{ product: createProduct({ price: 100 }), quantity: 5 },
{ product: createProduct({ price: 50 }), quantity: 2 }
]
});
```
## Faker Integration
### Setup Faker
```bash
npm install -D @faker-js/faker
```
```typescript
// factories/faker-user.factory.ts
import { faker } from '@faker-js/faker';
interface User {
id: string;
email: string;
name: string;
avatar: string;
address: {
street: string;
city: string;
country: string;
zipCode: string;
};
}
export function createFakeUser(overrides: Partial<User> = {}): User {
return {
id: faker.string.uuid(),
email: faker.internet.email(),
name: faker.person.fullName(),
avatar: faker.image.avatar(),
address: {
street: faker.location.streetAddress(),
city: faker.location.city(),
country: faker.location.country(),
zipCode: faker.location.zipCode()
},
...overrides
};
}
```
### Seeded Faker for Reproducibility
```typescript
import { faker } from '@faker-js/faker';
// Set seed for reproducible data
faker.seed(12345);
export function createDeterministicUser(): User {
return {
id: faker.string.uuid(),
email: faker.internet.email(),
name: faker.person.fullName()
// Same seed = same data every time
};
}
// Or seed per test
test('user profile', async ({ page }) => {
faker.seed(42); // Reset seed for this test
const user = createFakeUser();
// user will always have the same data
});
```
### Faker Fixture
```typescript
// fixtures/faker.fixture.ts
import { test as base } from '@playwright/test';
import { faker } from '@faker-js/faker';
type FakerFixtures = {
fake: typeof faker;
};
export const test = base.extend<FakerFixtures>({
fake: async ({}, use, testInfo) => {
// Seed based on test name for reproducibility
faker.seed(testInfo.title.length);
await use(faker);
}
});
// Usage
test('create user with fake data', async ({ page, fake }) => {
await page.goto('/signup');
await page.getByLabel('Name').fill(fake.person.fullName());
await page.getByLabel('Email').fill(fake.internet.email());
await page.getByLabel('Password').fill(fake.internet.password());
await page.getByRole('button', { name: 'Sign Up' }).click();
});
```
## Data-Driven Testing
### test.each with Arrays
```typescript
const loginScenarios = [
{ email: 'user@example.com', password: 'pass123', expected: 'Dashboard' },
{ email: 'admin@example.com', password: 'admin123', expected: 'Admin Panel' },
{
email: 'invalid@example.com',
password: 'wrong',
expected: 'Invalid credentials'
}
];
for (const { email, password, expected } of loginScenarios) {
test(`login with ${email}`, async ({ page }) => {
await page.goto('/login');
await page.getByLabel('Email').fill(email);
await page.getByLabel('Password').fill(password);
await page.getByRole('button', { name: 'Sign In' }).click();
await expect(page.getByText(expected)).toBeVisible();
});
}
```
### Parameterized Tests
```typescript
// data/checkout-scenarios.ts
export const checkoutScenarios = [
{
name: 'standard shipping',
shipping: 'standard',
expectedDays: '5-7 business days',
expectedCost: '$5.99'
},
{
name: 'express shipping',
shipping: 'express',
expectedDays: '2-3 business days',
expectedCost: '$14.99'
},
{
name: 'overnight shipping',
shipping: 'overnight',
expectedDays: 'Next business day',
expectedCost: '$29.99'
}
];
```
```typescript
import { checkoutScenarios } from './data/checkout-scenarios';
test.describe('shipping options', () => {
for (const scenario of checkoutScenarios) {
test(`checkout with ${scenario.name}`, async ({ page }) => {
await page.goto('/checkout');
await page.getByLabel(scenario.shipping, { exact: false }).check();
await expect(page.getByText(scenario.expectedDays)).toBeVisible();
await expect(page.getByText(scenario.expectedCost)).toBeVisible();
});
}
});
```
### CSV/JSON Data Source
```typescript
import fs from 'fs';
interface TestCase {
input: string;
expected: string;
}
// Load test data from JSON
const testCases: TestCase[] = JSON.parse(fs.readFileSync('./data/search-tests.json', 'utf-8'));
test.describe('search functionality', () => {
for (const { input, expected } of testCases) {
test(`search for "${input}"`, async ({ page }) => {
await page.goto('/search');
await page.getByLabel('Search').fill(input);
await page.getByLabel('Search').press('Enter');
await expect(page.getByText(expected)).toBeVisible();
});
}
});
```
## Test Data Fixtures
### Fixture with Factory
```typescript
// fixtures/data.fixture.ts
import { test as base } from '@playwright/test';
import { createUser, User } from '../factories/user.factory';
import { createProduct, Product } from '../factories/product.factory';
type DataFixtures = {
testUser: User;
testProducts: Product[];
};
export const test = base.extend<DataFixtures>({
testUser: async ({}, use) => {
const user = createUser({ name: 'E2E Test User' });
await use(user);
},
testProducts: async ({}, use) => {
const products = [
createProduct({ name: 'Test Product 1' }),
createProduct({ name: 'Test Product 2' }),
createProduct({ name: 'Test Product 3' })
];
await use(products);
}
});
// Usage
test('add product to cart', async ({ page, testUser, testProducts }) => {
// Mock API with test data
await page.route('**/api/user', (route) => route.fulfill({ json: testUser }));
await page.route('**/api/products', (route) => route.fulfill({ json: testProducts }));
await page.goto('/products');
await expect(page.getByText(testProducts[0].name)).toBeVisible();
});
```
## Database Seeding
### API-Based Seeding
```typescript
// fixtures/seed.fixture.ts
import { test as base, APIRequestContext } from '@playwright/test';
import { createUser } from '../factories/user.factory';
type SeedFixtures = {
seedUser: (overrides?: Partial<User>) => Promise<User>;
cleanupUsers: string[];
};
export const test = base.extend<SeedFixtures>({
cleanupUsers: [],
seedUser: async ({ request, cleanupUsers }, use) => {
await use(async (overrides = {}) => {
const userData = createUser(overrides);
const response = await request.post('/api/test/users', {
data: userData
});
const user = await response.json();
cleanupUsers.push(user.id);
return user;
});
},
// Cleanup after test
cleanupUsers: async ({ request }, use) => {
const userIds: string[] = [];
await use(userIds);
// Delete all created users
for (const id of userIds) {
await request.delete(`/api/test/users/${id}`);
}
}
});
// Usage
test('user profile page', async ({ page, seedUser }) => {
const user = await seedUser({ name: 'John Doe' });
await page.goto(`/users/${user.id}`);
await expect(page.getByText('John Doe')).toBeVisible();
});
```
### Transaction Rollback Seeding
```typescript
// fixtures/db.fixture.ts
export const test = base.extend<{}, { db: DbTransaction }>({
db: [
async ({}, use) => {
const client = await pool.connect();
await client.query('BEGIN');
await use({
query: (sql: string, params?: any[]) => client.query(sql, params),
seed: async (table: string, data: object) => {
const keys = Object.keys(data);
const values = Object.values(data);
const placeholders = keys.map((_, i) => `$${i + 1}`);
const result = await client.query(
`INSERT INTO ${table} (${keys.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *`,
values
);
return result.rows[0];
}
});
await client.query('ROLLBACK');
client.release();
},
{ scope: 'test' }
]
});
```
## Anti-Patterns to Avoid
| Anti-Pattern | Problem | Solution |
| ------------------------------- | ------------------------------- | -------------------------- |
| Hardcoded test data | Brittle, repetitive | Use factories |
| Random data without seed | Non-reproducible failures | Seed faker per test |
| Shared mutable test data | Tests interfere with each other | Create fresh data per test |
| Manual data creation everywhere | Duplication, maintenance burden | Centralize in factories |
## Related References
- **Fixtures**: See [fixtures-hooks.md](fixtures-hooks.md) for fixture patterns
- **API Testing**: See [test-suite-structure.md](test-suite-structure.md) for API mocking
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |