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.
testing-patterns/forms-validation.md
View on GitHub# Form Testing Patterns
## Table of Contents
1. [Quick Reference](#quick-reference)
2. [Patterns](#patterns)
3. [Decision Guide](#decision-guide)
4. [Anti-Patterns](#anti-patterns)
5. [Troubleshooting](#troubleshooting)
> **When to use**: Testing form filling, submission, validation messages, multi-step wizards, dynamic fields, and auto-complete interactions.
## Quick Reference
```typescript
// Text input
await page.getByLabel('Username').fill('john_doe');
// Select dropdown
await page.getByLabel('Region').selectOption('EU');
await page.getByLabel('Region').selectOption({ label: 'Europe' });
// Checkbox and radio
await page.getByLabel('Subscribe').check();
await page.getByLabel('Priority shipping').click();
// Date input
await page.getByLabel('Departure').fill('2025-08-20');
// Clear a field
await page.getByLabel('Username').clear();
// Submit
await page.getByRole('button', { name: 'Register' }).click();
// Verify validation error
await expect(page.getByText('Username is required')).toBeVisible();
```
## Patterns
### Auto-Complete and Typeahead Fields
**Use when**: Testing search fields, address lookups, mention pickers, or any input that shows suggestions as the user types.
```typescript
test('select from typeahead suggestions', async ({ page }) => {
await page.goto('/products');
const searchBox = page.getByRole('combobox', { name: 'Find product' });
await searchBox.pressSequentially('lapt', { delay: 100 });
const suggestionList = page.getByRole('listbox');
await expect(suggestionList).toBeVisible();
await suggestionList.getByRole('option', { name: 'Laptop Pro' }).click();
await expect(searchBox).toHaveValue('Laptop Pro');
});
test('typeahead with API-driven suggestions', async ({ page }) => {
await page.goto('/shipping');
const streetField = page.getByLabel('Street');
const responsePromise = page.waitForResponse('**/api/address-lookup*');
await streetField.pressSequentially('456 Elm', { delay: 50 });
await responsePromise;
await page.getByRole('option', { name: /456 Elm St/ }).click();
await expect(page.getByLabel('Town')).toHaveValue('Austin');
await expect(page.getByLabel('State')).toHaveValue('TX');
await expect(page.getByLabel('Postal code')).toHaveValue('78701');
});
test('dismiss suggestions and enter custom value', async ({ page }) => {
await page.goto('/labels');
const labelInput = page.getByLabel('New label');
await labelInput.pressSequentially('my-label');
await labelInput.press('Escape');
await expect(page.getByRole('listbox')).not.toBeVisible();
await labelInput.press('Enter');
await expect(page.getByText('my-label')).toBeVisible();
});
```
### Dynamic Forms — Conditional Fields
**Use when**: Form fields appear, disappear, or change based on the value of other fields.
```typescript
test('conditional fields appear based on selection', async ({ page }) => {
await page.goto('/loan/apply');
await page.getByLabel('Applicant type').selectOption('corporate');
await expect(page.getByLabel('Business name')).toBeVisible();
await expect(page.getByLabel('EIN')).toBeVisible();
await page.getByLabel('Business name').fill('TechCorp Inc');
await page.getByLabel('EIN').fill('98-7654321');
await page.getByLabel('Applicant type').selectOption('individual');
await expect(page.getByLabel('Business name')).not.toBeVisible();
await expect(page.getByLabel('EIN')).not.toBeVisible();
});
test('checkbox toggles additional section', async ({ page }) => {
await page.goto('/delivery');
await page.getByLabel('Separate invoice address').check();
const invoiceSection = page.getByRole('group', { name: 'Invoice address' });
await expect(invoiceSection).toBeVisible();
await invoiceSection.getByLabel('Address').fill('789 Pine Rd');
await invoiceSection.getByLabel('City').fill('Denver');
await page.getByLabel('Separate invoice address').uncheck();
await expect(invoiceSection).not.toBeVisible();
});
test('dependent dropdown chains', async ({ page }) => {
await page.goto('/region-selector');
await page.getByLabel('Country').selectOption('CA');
const provinceDropdown = page.getByLabel('Province');
await expect(provinceDropdown.getByRole('option')).not.toHaveCount(0);
await provinceDropdown.selectOption('ON');
const cityDropdown = page.getByLabel('City');
await expect(cityDropdown.getByRole('option')).not.toHaveCount(0);
await cityDropdown.selectOption({ label: 'Toronto' });
});
```
### Multi-Step Forms and Wizards
**Use when**: The form spans multiple pages or steps, with next/previous navigation and per-step validation.
```typescript
test('complete a multi-step booking wizard', async ({ page }) => {
await page.goto('/booking');
await test.step('enter guest information', async () => {
await expect(page.getByRole('heading', { name: 'Guest Info' })).toBeVisible();
await page.getByLabel('Full name').fill('Alice Smith');
await page.getByLabel('Email').fill('alice@test.com');
await page.getByLabel('Phone').fill('555-1234');
await page.getByRole('button', { name: 'Next' }).click();
});
await test.step('select room options', async () => {
await expect(page.getByRole('heading', { name: 'Room Selection' })).toBeVisible();
await page.getByLabel('Room type').selectOption('suite');
await page.getByLabel('Check-in').fill('2025-09-01');
await page.getByLabel('Check-out').fill('2025-09-05');
await page.getByRole('button', { name: 'Next' }).click();
});
await test.step('confirm booking', async () => {
await expect(page.getByRole('heading', { name: 'Confirmation' })).toBeVisible();
await expect(page.getByText('Alice Smith')).toBeVisible();
await expect(page.getByText('suite')).toBeVisible();
await page.getByRole('button', { name: 'Confirm booking' }).click();
});
await expect(page.getByRole('heading', { name: 'Booking complete' })).toBeVisible();
});
test('wizard validates each step before proceeding', async ({ page }) => {
await page.goto('/booking');
await page.getByRole('button', { name: 'Next' }).click();
await expect(page.getByRole('heading', { name: 'Guest Info' })).toBeVisible();
await expect(page.getByText('Full name is required')).toBeVisible();
});
test('wizard supports going back without losing data', async ({ page }) => {
await page.goto('/booking');
await page.getByLabel('Full name').fill('Alice Smith');
await page.getByLabel('Email').fill('alice@test.com');
await page.getByLabel('Phone').fill('555-1234');
await page.getByRole('button', { name: 'Next' }).click();
await page.getByRole('button', { name: 'Previous' }).click();
await expect(page.getByLabel('Full name')).toHaveValue('Alice Smith');
await expect(page.getByLabel('Email')).toHaveValue('alice@test.com');
});
```
### Form Submission and Response Handling
**Use when**: Testing what happens after a form is submitted — success messages, redirects, error responses from the server, and loading states during submission.
```typescript
test('successful form submission shows confirmation', async ({ page }) => {
await page.goto('/feedback');
await page.getByLabel('Subject').fill('Feature request');
await page.getByLabel('Email').fill('user@test.com');
await page.getByLabel('Details').fill('Please add dark mode');
const responsePromise = page.waitForResponse('**/api/feedback');
await page.getByRole('button', { name: 'Submit feedback' }).click();
const response = await responsePromise;
expect(response.status()).toBe(200);
await expect(page.getByText('Feedback received')).toBeVisible();
});
test('form submission shows server-side validation errors', async ({ page }) => {
await page.goto('/signup');
await page.getByLabel('Email').fill('existing@test.com');
await page.getByLabel('Password', { exact: true }).fill('Secure1@pass');
await page.getByRole('button', { name: 'Sign up' }).click();
await expect(page.getByText('Email address already registered')).toBeVisible();
});
test('form shows loading state during submission', async ({ page }) => {
await page.goto('/feedback');
await page.getByLabel('Subject').fill('Bug report');
await page.getByLabel('Email').fill('user@test.com');
await page.getByLabel('Details').fill('Found an issue');
const submit = page.getByRole('button', {
name: /Submit feedback|Submitting/
});
await submit.click();
await expect(submit).toHaveText(/Submitting/);
await expect(submit).toBeDisabled();
await expect(submit).toHaveText('Submit feedback');
await expect(submit).toBeEnabled();
});
test('form redirects after successful submission', async ({ page }) => {
await page.goto('/auth/login');
await page.getByLabel('Email').fill('admin@test.com');
await page.getByLabel('Password').fill('admin123');
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForURL('/home');
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
});
```
### Filling Basic Form Fields
**Use when**: Testing any form with standard HTML inputs — text, email, password, number, textarea, select, checkbox, radio.
```typescript
test('fill and submit a signup form', async ({ page }) => {
await page.goto('/signup');
await page.getByLabel('First name').fill('Bob');
await page.getByLabel('Last name').fill('Wilson');
await page.getByLabel('Email').fill('bob@test.com');
await page.getByLabel('Password', { exact: true }).fill('P@ssw0rd!');
await page.getByLabel('Confirm password').fill('P@ssw0rd!');
await page.getByLabel('About you').fill('Developer with 5 years experience.');
await page.getByLabel('Years of experience').fill('5');
await page.getByLabel('Country').selectOption('UK');
await page.getByLabel('City').selectOption({ label: 'London' });
await page.getByLabel('Skills').selectOption(['typescript', 'playwright', 'nodejs']);
await page.getByLabel('Accept terms').check();
await expect(page.getByLabel('Accept terms')).toBeChecked();
await page.getByLabel('Annual billing').check();
await expect(page.getByLabel('Annual billing')).toBeChecked();
await page.getByRole('button', { name: 'Create account' }).click();
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
});
```
### Date and Time Inputs
**Use when**: Testing native `<input type="date">`, `<input type="time">`, `<input type="datetime-local">`, or third-party date pickers.
```typescript
test('fill native date and time inputs', async ({ page }) => {
await page.goto('/reservation');
await page.getByLabel('Reservation date').fill('2025-07-10');
await expect(page.getByLabel('Reservation date')).toHaveValue('2025-07-10');
await page.getByLabel('Time slot').fill('18:00');
await page.getByLabel('Reminder').fill('2025-07-10T17:30');
});
test('interact with a third-party date picker', async ({ page }) => {
await page.goto('/reservation');
await page.getByLabel('Event date').click();
await page.getByRole('button', { name: 'Next month' }).click();
await page.getByRole('gridcell', { name: '25' }).click();
await expect(page.getByLabel('Event date')).toHaveValue(/2025/);
});
```
### Required Field Validation
**Use when**: Testing that the form shows appropriate error messages when required fields are empty.
```typescript
test('shows validation errors for empty required fields', async ({ page }) => {
await page.goto('/inquiry');
await page.getByRole('button', { name: 'Send inquiry' }).click();
await expect(page.getByText('Name is required')).toBeVisible();
await expect(page.getByText('Email is required')).toBeVisible();
await expect(page.getByText('Question is required')).toBeVisible();
await expect(page).toHaveURL(/\/inquiry/);
});
test('clears validation errors when fields are filled', async ({ page }) => {
await page.goto('/inquiry');
await page.getByRole('button', { name: 'Send inquiry' }).click();
await expect(page.getByText('Name is required')).toBeVisible();
await page.getByLabel('Name').fill('Carol Brown');
await page.getByLabel('Email').focus();
await expect(page.getByText('Name is required')).not.toBeVisible();
});
test('native HTML5 validation with required attribute', async ({ page }) => {
await page.goto('/basic-form');
await page.getByRole('button', { name: 'Submit' }).click();
const emailInput = page.getByLabel('Email');
const validationMessage = await emailInput.evaluate((el: HTMLInputElement) => el.validationMessage);
expect(validationMessage).toBeTruthy();
});
```
### Format Validation and Custom Rules
**Use when**: Testing email format, phone number format, password strength, and business-specific validation rules.
```typescript
test('validates email format', async ({ page }) => {
await page.goto('/signup');
const emailField = page.getByLabel('Email');
const invalidEmails = ['invalid', 'missing@', '@nodomain.com', 'has spaces@mail.com'];
for (const email of invalidEmails) {
await emailField.fill(email);
await emailField.blur();
await expect(page.getByText('Enter a valid email address')).toBeVisible();
}
await emailField.fill('correct@domain.com');
await emailField.blur();
await expect(page.getByText('Enter a valid email address')).not.toBeVisible();
});
test('validates password strength rules', async ({ page }) => {
await page.goto('/signup');
const passwordField = page.getByLabel('Password', { exact: true });
await passwordField.fill('Xy1!');
await passwordField.blur();
await expect(page.getByText('Minimum 8 characters')).toBeVisible();
await passwordField.fill('lowercase1!');
await passwordField.blur();
await expect(page.getByText('Include an uppercase letter')).toBeVisible();
await passwordField.fill('SecureP@ss1');
await passwordField.blur();
await expect(page.getByText(/Minimum|Include/)).not.toBeVisible();
});
test('validates custom business rule — minimum amount', async ({ page }) => {
await page.goto('/transfer');
await page.getByLabel('Amount').fill('5');
await page.getByLabel('Amount').blur();
await expect(page.getByText('Minimum transfer is $10')).toBeVisible();
await page.getByLabel('Amount').fill('1000000');
await page.getByLabel('Amount').blur();
await expect(page.getByText('Maximum transfer is $100,000')).toBeVisible();
await page.getByLabel('Amount').fill('500');
await page.getByLabel('Amount').blur();
await expect(page.getByText(/Minimum|Maximum/)).not.toBeVisible();
});
```
### Form Reset Testing
**Use when**: Testing "clear form" or "reset" functionality, verifying that fields return to their default values.
```typescript
test('reset button clears all fields to defaults', async ({ page }) => {
await page.goto('/preferences');
await page.getByLabel('Nickname').fill('CustomNick');
await page.getByLabel('Language').selectOption('es');
await page.getByLabel('Email alerts').uncheck();
await page.getByRole('button', { name: 'Reset' }).click();
await expect(page.getByLabel('Nickname')).toHaveValue('');
await expect(page.getByLabel('Language')).toHaveValue('en');
await expect(page.getByLabel('Email alerts')).toBeChecked();
});
test('confirmation dialog before resetting a dirty form', async ({ page }) => {
await page.goto('/document');
await page.getByLabel('Document title').fill('Draft document');
page.on('dialog', (dialog) => dialog.accept());
await page.getByRole('button', { name: 'Clear changes' }).click();
await expect(page.getByLabel('Document title')).toHaveValue('');
});
```
## Decision Guide
| Scenario | Approach | Key API |
| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ |
| Standard text input | `fill()` (clears, then types) | `page.getByLabel('Field').fill('value')` |
| Need keystroke events (autocomplete) | `pressSequentially()` with delay | `locator.pressSequentially('text', { delay: 100 })` |
| Native `<select>` dropdown | `selectOption()` by value or label | `locator.selectOption('US')` or `{ label: 'United States' }` |
| Custom dropdown (ARIA listbox) | Click trigger, then select option role | `getByRole('option', { name: '...' }).click()` |
| Checkbox | `check()` / `uncheck()` (idempotent) | `locator.check()` — safe to call even if already checked |
| Radio button | `check()` on the target radio | `page.getByLabel('Option').check()` |
| Date input (native) | `fill()` with ISO format | `locator.fill('2025-03-15')` |
| Date picker (third-party) | Click to open, navigate, select day | `getByRole('gridcell', { name: '15' }).click()` |
| Validation errors | Submit, then assert error text | `expect(page.getByText('Required')).toBeVisible()` |
| Multi-step wizard | `test.step()` per step, assert heading | `await test.step('Step 1', async () => { ... })` |
| Conditional/dynamic fields | Change trigger field, assert new field visibility | `expect(locator).toBeVisible()` / `.not.toBeVisible()` |
| Form submission | `waitForResponse` + click submit | Register response listener before click |
| Auto-complete | `pressSequentially()`, wait for listbox, select option | `getByRole('option', { name }).click()` |
| Form reset | Click reset, assert default values | `expect(locator).toHaveValue('')` |
## Anti-Patterns
| Don't Do This | Problem | Do This Instead |
| ------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| `await page.getByLabel('Field').type('value')` | `type()` appends to existing content; does not clear first | `await page.getByLabel('Field').fill('value')` |
| `await page.getByLabel('Option').click()` | `click()` toggles — if already checked, it unchecks | `await page.getByLabel('Option').check()` |
| `await page.fill('#email', 'test@test.com')` | CSS selector is fragile | `await page.getByLabel('Email').fill('test@test.com')` |
| `await page.selectOption('select', 'US')` without label | Targets first `<select>` on page; ambiguous | `await page.getByLabel('Country').selectOption('US')` |
| Testing every invalid input in one test | Test becomes huge, slow, and hard to debug | One test per validation rule or group related rules |
| `expect(await input.inputValue()).toBe('value')` | Resolves once — no retry. Race condition. | `await expect(input).toHaveValue('value')` |
| Filling fields with `page.evaluate()` | Bypasses event handlers (no `input`, `change` events fire) | Use `fill()` or `pressSequentially()` |
| Not waiting for conditional fields before filling | `fill()` fails on hidden/detached elements | `await expect(field).toBeVisible()` first |
| Hardcoding wait after selecting a dropdown | `waitForTimeout(500)` is flaky and slow | Wait for the dependent element to appear |
| Skipping server-side validation tests | Client-side validation can be bypassed | Test both client-side UX and server response |
## Troubleshooting
### `fill()` does nothing or clears but doesn't type
**Cause**: The input field uses a contenteditable div (rich text editors), not a real `<input>` or `<textarea>`.
```typescript
const isContentEditable = await page.getByTestId('editor').evaluate((el) => el.getAttribute('contenteditable'));
if (isContentEditable) {
await page.getByTestId('editor').click();
await page.getByTestId('editor').pressSequentially('Hello world');
}
```
### Date picker does not accept `fill()` value
**Cause**: Third-party date pickers often render custom UI over a hidden input. `fill()` sets the hidden input but the UI does not update.
```typescript
await page.getByLabel('Date').click();
await page.getByRole('button', { name: 'Next month' }).click();
await page.getByRole('gridcell', { name: '15' }).click();
// Alternatively, if the library reads from the input on change:
await page.getByLabel('Date').fill('2025-06-15');
await page.getByLabel('Date').dispatchEvent('change');
```
### `selectOption()` throws "not a select element"
**Cause**: The dropdown is a custom component (ARIA listbox), not a native `<select>`.
```typescript
await page.getByRole('combobox', { name: 'Country' }).click();
await page.getByRole('option', { name: 'United States' }).click();
```
### Validation errors do not appear after `fill()` and submit
**Cause**: The validation triggers on `blur` (focus leaving the field), but `fill()` does not trigger blur automatically.
```typescript
await page.getByLabel('Email').fill('invalid');
await page.getByLabel('Email').blur();
await expect(page.getByText('Enter a valid email')).toBeVisible();
// Or move focus to the next field
await page.getByLabel('Password').focus();
```
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 |