@assertrx/dino 1.0.0

package/skills/playwright-core/forms-and-validation.md

@@ -0,0 +1,1056 @@
+# Forms and Validation
+
+> **When to use**: Testing form filling, submission, validation messages, multi-step wizards, dynamic fields, and auto-complete interactions.
+> **Prerequisites**: [core/locators.md](locators.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)
+
+## Quick Reference
+
+```typescript
+// Text input
+await page.getByLabel('Name').fill('Jane Doe');
+
+// Select dropdown
+await page.getByLabel('Country').selectOption('US');
+await page.getByLabel('Country').selectOption({ label: 'United States' });
+
+// Checkbox and radio
+await page.getByLabel('Remember me').check();
+await page.getByLabel('Express shipping').click();
+
+// Date input
+await page.getByLabel('Start date').fill('2025-03-15');
+
+// Clear a field
+await page.getByLabel('Name').clear();
+
+// Submit
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Verify validation error
+await expect(page.getByText('Email is required')).toBeVisible();
+```
+
+## Patterns
+
+### Filling Basic Form Fields
+
+**Use when**: Testing any form with standard HTML inputs — text, email, password, number, textarea, select, checkbox, radio.
+**Avoid when**: Never. This is the foundation pattern.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('fill and submit a registration form', async ({ page }) => {
+  await page.goto('/register');
+
+  // Text inputs — use fill() which clears first, not type()
+  await page.getByLabel('First name').fill('Jane');
+  await page.getByLabel('Last name').fill('Doe');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('S3cureP@ss!');
+  await page.getByLabel('Confirm password').fill('S3cureP@ss!');
+
+  // Textarea
+  await page.getByLabel('Bio').fill('Software engineer with 10 years of experience.');
+
+  // Number input
+  await page.getByLabel('Age').fill('32');
+
+  // Native <select>
+  await page.getByLabel('Country').selectOption('US');
+
+  // Select by visible label text (when value differs from display text)
+  await page.getByLabel('State').selectOption({ label: 'California' });
+
+  // Multi-select
+  await page.getByLabel('Interests').selectOption(['coding', 'testing', 'devops']);
+
+  // Checkbox — use check() not click() (idempotent: won't uncheck if already checked)
+  await page.getByLabel('I agree to the terms').check();
+  await expect(page.getByLabel('I agree to the terms')).toBeChecked();
+
+  // Radio button
+  await page.getByLabel('Monthly billing').check();
+  await expect(page.getByLabel('Monthly billing')).toBeChecked();
+
+  // Submit
+  await page.getByRole('button', { name: 'Create account' }).click();
+  await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('fill and submit a registration form', async ({ page }) => {
+  await page.goto('/register');
+
+  await page.getByLabel('First name').fill('Jane');
+  await page.getByLabel('Last name').fill('Doe');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('S3cureP@ss!');
+  await page.getByLabel('Confirm password').fill('S3cureP@ss!');
+
+  await page.getByLabel('Bio').fill('Software engineer with 10 years of experience.');
+  await page.getByLabel('Age').fill('32');
+  await page.getByLabel('Country').selectOption('US');
+  await page.getByLabel('State').selectOption({ label: 'California' });
+  await page.getByLabel('Interests').selectOption(['coding', 'testing', 'devops']);
+
+  await page.getByLabel('I agree to the terms').check();
+  await expect(page.getByLabel('I agree to the terms')).toBeChecked();
+
+  await page.getByLabel('Monthly billing').check();
+  await expect(page.getByLabel('Monthly 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.
+**Avoid when**: The date picker is a simple text field with no special input type. Just use `fill()`.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('fill native date and time inputs', async ({ page }) => {
+  await page.goto('/booking');
+
+  // Native date input — use ISO format YYYY-MM-DD
+  await page.getByLabel('Check-in date').fill('2025-06-15');
+  await expect(page.getByLabel('Check-in date')).toHaveValue('2025-06-15');
+
+  // Native time input — use HH:MM format
+  await page.getByLabel('Arrival time').fill('14:30');
+
+  // datetime-local — use YYYY-MM-DDTHH:MM format
+  await page.getByLabel('Event start').fill('2025-06-15T09:00');
+});
+
+test('interact with a third-party date picker', async ({ page }) => {
+  await page.goto('/booking');
+
+  // Click to open the date picker
+  await page.getByLabel('Departure date').click();
+
+  // Navigate months if needed
+  await page.getByRole('button', { name: 'Next month' }).click();
+
+  // Select a specific day
+  await page.getByRole('gridcell', { name: '20' }).click();
+
+  // Verify the selected date appears in the input
+  await expect(page.getByLabel('Departure date')).toHaveValue(/2025/);
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('fill native date and time inputs', async ({ page }) => {
+  await page.goto('/booking');
+
+  await page.getByLabel('Check-in date').fill('2025-06-15');
+  await expect(page.getByLabel('Check-in date')).toHaveValue('2025-06-15');
+
+  await page.getByLabel('Arrival time').fill('14:30');
+  await page.getByLabel('Event start').fill('2025-06-15T09:00');
+});
+
+test('interact with a third-party date picker', async ({ page }) => {
+  await page.goto('/booking');
+
+  await page.getByLabel('Departure date').click();
+  await page.getByRole('button', { name: 'Next month' }).click();
+  await page.getByRole('gridcell', { name: '20' }).click();
+
+  await expect(page.getByLabel('Departure date')).toHaveValue(/2025/);
+});
+```
+
+### Required Field Validation
+
+**Use when**: Testing that the form shows appropriate error messages when required fields are empty.
+**Avoid when**: You only care about the happy path. Validation tests should complement, not replace, success path tests.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('shows validation errors for empty required fields', async ({ page }) => {
+  await page.goto('/contact');
+
+  // Submit without filling anything
+  await page.getByRole('button', { name: 'Send message' }).click();
+
+  // Verify all required field errors appear
+  await expect(page.getByText('Name is required')).toBeVisible();
+  await expect(page.getByText('Email is required')).toBeVisible();
+  await expect(page.getByText('Message is required')).toBeVisible();
+
+  // Verify the form was NOT submitted (still on the same page)
+  await expect(page).toHaveURL(/\/contact/);
+});
+
+test('clears validation errors when fields are filled', async ({ page }) => {
+  await page.goto('/contact');
+
+  // Trigger errors
+  await page.getByRole('button', { name: 'Send message' }).click();
+  await expect(page.getByText('Name is required')).toBeVisible();
+
+  // Fill the field — error should disappear
+  await page.getByLabel('Name').fill('Jane Doe');
+
+  // Use tab or click away to trigger blur validation
+  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('/simple-form');
+
+  await page.getByRole('button', { name: 'Submit' }).click();
+
+  // Check for native validation message via the :invalid pseudo-class
+  const emailInput = page.getByLabel('Email');
+  const validationMessage = await emailInput.evaluate(
+    (el: HTMLInputElement) => el.validationMessage
+  );
+  expect(validationMessage).toBeTruthy();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('shows validation errors for empty required fields', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByRole('button', { name: 'Send message' }).click();
+
+  await expect(page.getByText('Name is required')).toBeVisible();
+  await expect(page.getByText('Email is required')).toBeVisible();
+  await expect(page.getByText('Message is required')).toBeVisible();
+
+  await expect(page).toHaveURL(/\/contact/);
+});
+
+test('clears validation errors when fields are filled', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByRole('button', { name: 'Send message' }).click();
+  await expect(page.getByText('Name is required')).toBeVisible();
+
+  await page.getByLabel('Name').fill('Jane Doe');
+  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('/simple-form');
+
+  await page.getByRole('button', { name: 'Submit' }).click();
+
+  const emailInput = page.getByLabel('Email');
+  const validationMessage = await emailInput.evaluate(
+    (el) => 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.
+**Avoid when**: The validation is purely server-side with no client-side feedback. Test via API instead.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('validates email format', async ({ page }) => {
+  await page.goto('/register');
+
+  const emailField = page.getByLabel('Email');
+
+  // Invalid formats
+  const invalidEmails = ['not-an-email', 'missing@', '@no-local.com', 'spaces in@email.com'];
+
+  for (const email of invalidEmails) {
+    await emailField.fill(email);
+    await emailField.blur();
+    await expect(page.getByText('Please enter a valid email')).toBeVisible();
+  }
+
+  // Valid format clears the error
+  await emailField.fill('valid@example.com');
+  await emailField.blur();
+  await expect(page.getByText('Please enter a valid email')).not.toBeVisible();
+});
+
+test('validates password strength rules', async ({ page }) => {
+  await page.goto('/register');
+
+  const passwordField = page.getByLabel('Password', { exact: true });
+
+  // Too short
+  await passwordField.fill('Ab1!');
+  await passwordField.blur();
+  await expect(page.getByText('At least 8 characters')).toBeVisible();
+
+  // Missing uppercase
+  await passwordField.fill('abcdefg1!');
+  await passwordField.blur();
+  await expect(page.getByText('At least one uppercase letter')).toBeVisible();
+
+  // Strong password — all checks pass
+  await passwordField.fill('Str0ngP@ss!');
+  await passwordField.blur();
+  await expect(page.getByText(/At least/)).not.toBeVisible();
+});
+
+test('validates custom business rule — age range', async ({ page }) => {
+  await page.goto('/insurance/quote');
+
+  await page.getByLabel('Age').fill('15');
+  await page.getByLabel('Age').blur();
+  await expect(page.getByText('Must be 18 or older')).toBeVisible();
+
+  await page.getByLabel('Age').fill('150');
+  await page.getByLabel('Age').blur();
+  await expect(page.getByText('Please enter a valid age')).toBeVisible();
+
+  await page.getByLabel('Age').fill('30');
+  await page.getByLabel('Age').blur();
+  await expect(page.getByText(/Must be|valid age/)).not.toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('validates email format', async ({ page }) => {
+  await page.goto('/register');
+
+  const emailField = page.getByLabel('Email');
+
+  const invalidEmails = ['not-an-email', 'missing@', '@no-local.com', 'spaces in@email.com'];
+
+  for (const email of invalidEmails) {
+    await emailField.fill(email);
+    await emailField.blur();
+    await expect(page.getByText('Please enter a valid email')).toBeVisible();
+  }
+
+  await emailField.fill('valid@example.com');
+  await emailField.blur();
+  await expect(page.getByText('Please enter a valid email')).not.toBeVisible();
+});
+
+test('validates password strength rules', async ({ page }) => {
+  await page.goto('/register');
+
+  const passwordField = page.getByLabel('Password', { exact: true });
+
+  await passwordField.fill('Ab1!');
+  await passwordField.blur();
+  await expect(page.getByText('At least 8 characters')).toBeVisible();
+
+  await passwordField.fill('abcdefg1!');
+  await passwordField.blur();
+  await expect(page.getByText('At least one uppercase letter')).toBeVisible();
+
+  await passwordField.fill('Str0ngP@ss!');
+  await passwordField.blur();
+  await expect(page.getByText(/At least/)).not.toBeVisible();
+});
+
+test('validates custom business rule — age range', async ({ page }) => {
+  await page.goto('/insurance/quote');
+
+  await page.getByLabel('Age').fill('15');
+  await page.getByLabel('Age').blur();
+  await expect(page.getByText('Must be 18 or older')).toBeVisible();
+
+  await page.getByLabel('Age').fill('150');
+  await page.getByLabel('Age').blur();
+  await expect(page.getByText('Please enter a valid age')).toBeVisible();
+
+  await page.getByLabel('Age').fill('30');
+  await page.getByLabel('Age').blur();
+  await expect(page.getByText(/Must be|valid age/)).not.toBeVisible();
+});
+```
+
+### Multi-Step Forms and Wizards
+
+**Use when**: The form spans multiple pages or steps, with next/previous navigation and per-step validation.
+**Avoid when**: The form is a single page. Use the basic form filling pattern.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('complete a multi-step checkout wizard', async ({ page }) => {
+  await page.goto('/checkout');
+
+  // Step 1: Shipping
+  await test.step('fill shipping information', async () => {
+    await expect(page.getByRole('heading', { name: 'Shipping' })).toBeVisible();
+
+    await page.getByLabel('Address').fill('123 Main St');
+    await page.getByLabel('City').fill('Portland');
+    await page.getByLabel('State').selectOption('OR');
+    await page.getByLabel('ZIP code').fill('97201');
+
+    await page.getByRole('button', { name: 'Continue' }).click();
+  });
+
+  // Step 2: Payment
+  await test.step('fill payment details', async () => {
+    await expect(page.getByRole('heading', { name: 'Payment' })).toBeVisible();
+
+    await page.getByLabel('Card number').fill('4242424242424242');
+    await page.getByLabel('Expiration').fill('12/28');
+    await page.getByLabel('CVC').fill('123');
+
+    await page.getByRole('button', { name: 'Continue' }).click();
+  });
+
+  // Step 3: Review
+  await test.step('review and confirm order', async () => {
+    await expect(page.getByRole('heading', { name: 'Review' })).toBeVisible();
+
+    // Verify data from previous steps is shown
+    await expect(page.getByText('123 Main St')).toBeVisible();
+    await expect(page.getByText('ending in 4242')).toBeVisible();
+
+    await page.getByRole('button', { name: 'Place order' }).click();
+  });
+
+  // Confirmation
+  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
+});
+
+test('wizard validates each step before proceeding', async ({ page }) => {
+  await page.goto('/checkout');
+
+  // Try to skip step 1 without filling required fields
+  await page.getByRole('button', { name: 'Continue' }).click();
+
+  // Should stay on step 1 with validation errors
+  await expect(page.getByRole('heading', { name: 'Shipping' })).toBeVisible();
+  await expect(page.getByText('Address is required')).toBeVisible();
+});
+
+test('wizard supports going back without losing data', async ({ page }) => {
+  await page.goto('/checkout');
+
+  // Fill step 1
+  await page.getByLabel('Address').fill('123 Main St');
+  await page.getByLabel('City').fill('Portland');
+  await page.getByLabel('State').selectOption('OR');
+  await page.getByLabel('ZIP code').fill('97201');
+  await page.getByRole('button', { name: 'Continue' }).click();
+
+  // Go back from step 2
+  await page.getByRole('button', { name: 'Back' }).click();
+
+  // Verify step 1 data is preserved
+  await expect(page.getByLabel('Address')).toHaveValue('123 Main St');
+  await expect(page.getByLabel('City')).toHaveValue('Portland');
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('complete a multi-step checkout wizard', async ({ page }) => {
+  await page.goto('/checkout');
+
+  await test.step('fill shipping information', async () => {
+    await expect(page.getByRole('heading', { name: 'Shipping' })).toBeVisible();
+
+    await page.getByLabel('Address').fill('123 Main St');
+    await page.getByLabel('City').fill('Portland');
+    await page.getByLabel('State').selectOption('OR');
+    await page.getByLabel('ZIP code').fill('97201');
+
+    await page.getByRole('button', { name: 'Continue' }).click();
+  });
+
+  await test.step('fill payment details', async () => {
+    await expect(page.getByRole('heading', { name: 'Payment' })).toBeVisible();
+
+    await page.getByLabel('Card number').fill('4242424242424242');
+    await page.getByLabel('Expiration').fill('12/28');
+    await page.getByLabel('CVC').fill('123');
+
+    await page.getByRole('button', { name: 'Continue' }).click();
+  });
+
+  await test.step('review and confirm order', async () => {
+    await expect(page.getByRole('heading', { name: 'Review' })).toBeVisible();
+
+    await expect(page.getByText('123 Main St')).toBeVisible();
+    await expect(page.getByText('ending in 4242')).toBeVisible();
+
+    await page.getByRole('button', { name: 'Place order' }).click();
+  });
+
+  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
+});
+
+test('wizard validates each step before proceeding', async ({ page }) => {
+  await page.goto('/checkout');
+
+  await page.getByRole('button', { name: 'Continue' }).click();
+
+  await expect(page.getByRole('heading', { name: 'Shipping' })).toBeVisible();
+  await expect(page.getByText('Address is required')).toBeVisible();
+});
+
+test('wizard supports going back without losing data', async ({ page }) => {
+  await page.goto('/checkout');
+
+  await page.getByLabel('Address').fill('123 Main St');
+  await page.getByLabel('City').fill('Portland');
+  await page.getByLabel('State').selectOption('OR');
+  await page.getByLabel('ZIP code').fill('97201');
+  await page.getByRole('button', { name: 'Continue' }).click();
+
+  await page.getByRole('button', { name: 'Back' }).click();
+
+  await expect(page.getByLabel('Address')).toHaveValue('123 Main St');
+  await expect(page.getByLabel('City')).toHaveValue('Portland');
+});
+```
+
+### Auto-Complete and Typeahead Fields
+
+**Use when**: Testing search fields, address lookups, mention pickers, or any input that shows suggestions as the user types.
+**Avoid when**: The field is a plain text input with no suggestions.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('select from auto-complete suggestions', async ({ page }) => {
+  await page.goto('/search');
+
+  const searchField = page.getByRole('combobox', { name: 'Search' });
+
+  // Type slowly enough for suggestions to appear
+  // pressSequentially simulates real keystrokes (triggers keydown/keyup/input events)
+  await searchField.pressSequentially('playw', { delay: 100 });
+
+  // Wait for the suggestion list to appear
+  const suggestions = page.getByRole('listbox');
+  await expect(suggestions).toBeVisible();
+
+  // Select a specific suggestion
+  await suggestions.getByRole('option', { name: 'Playwright Testing' }).click();
+
+  // Verify the selection populated the field
+  await expect(searchField).toHaveValue('Playwright Testing');
+});
+
+test('auto-complete with API-driven suggestions', async ({ page }) => {
+  await page.goto('/address-form');
+
+  const addressField = page.getByLabel('Address');
+  await addressField.pressSequentially('123 Ma', { delay: 50 });
+
+  // Wait for the API-driven suggestion list
+  const responsePromise = page.waitForResponse('**/api/address-suggest*');
+  await responsePromise;
+
+  await page.getByRole('option', { name: /123 Main St/ }).click();
+
+  // Verify dependent fields were auto-populated
+  await expect(page.getByLabel('City')).toHaveValue('Portland');
+  await expect(page.getByLabel('State')).toHaveValue('OR');
+  await expect(page.getByLabel('ZIP code')).toHaveValue('97201');
+});
+
+test('dismiss auto-complete and use custom value', async ({ page }) => {
+  await page.goto('/tags');
+
+  const tagInput = page.getByLabel('Add tag');
+  await tagInput.pressSequentially('custom-tag');
+
+  // Dismiss suggestions with Escape
+  await tagInput.press('Escape');
+  await expect(page.getByRole('listbox')).not.toBeVisible();
+
+  // Submit custom value with Enter
+  await tagInput.press('Enter');
+  await expect(page.getByText('custom-tag')).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('select from auto-complete suggestions', async ({ page }) => {
+  await page.goto('/search');
+
+  const searchField = page.getByRole('combobox', { name: 'Search' });
+  await searchField.pressSequentially('playw', { delay: 100 });
+
+  const suggestions = page.getByRole('listbox');
+  await expect(suggestions).toBeVisible();
+
+  await suggestions.getByRole('option', { name: 'Playwright Testing' }).click();
+  await expect(searchField).toHaveValue('Playwright Testing');
+});
+
+test('auto-complete with API-driven suggestions', async ({ page }) => {
+  await page.goto('/address-form');
+
+  const addressField = page.getByLabel('Address');
+  await addressField.pressSequentially('123 Ma', { delay: 50 });
+
+  const responsePromise = page.waitForResponse('**/api/address-suggest*');
+  await responsePromise;
+
+  await page.getByRole('option', { name: /123 Main St/ }).click();
+
+  await expect(page.getByLabel('City')).toHaveValue('Portland');
+  await expect(page.getByLabel('State')).toHaveValue('OR');
+  await expect(page.getByLabel('ZIP code')).toHaveValue('97201');
+});
+
+test('dismiss auto-complete and use custom value', async ({ page }) => {
+  await page.goto('/tags');
+
+  const tagInput = page.getByLabel('Add tag');
+  await tagInput.pressSequentially('custom-tag');
+
+  await tagInput.press('Escape');
+  await expect(page.getByRole('listbox')).not.toBeVisible();
+
+  await tagInput.press('Enter');
+  await expect(page.getByText('custom-tag')).toBeVisible();
+});
+```
+
+### Dynamic Forms — Conditional Fields
+
+**Use when**: Form fields appear, disappear, or change based on the value of other fields.
+**Avoid when**: All fields are always visible. Use the basic form filling pattern.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('conditional fields appear based on selection', async ({ page }) => {
+  await page.goto('/insurance/apply');
+
+  // Selecting "Business" shows additional fields
+  await page.getByLabel('Account type').selectOption('business');
+
+  // Wait for conditional fields to appear
+  await expect(page.getByLabel('Company name')).toBeVisible();
+  await expect(page.getByLabel('Tax ID')).toBeVisible();
+
+  await page.getByLabel('Company name').fill('Acme Corp');
+  await page.getByLabel('Tax ID').fill('12-3456789');
+
+  // Switching back to "Personal" hides them
+  await page.getByLabel('Account type').selectOption('personal');
+  await expect(page.getByLabel('Company name')).not.toBeVisible();
+  await expect(page.getByLabel('Tax ID')).not.toBeVisible();
+});
+
+test('checkbox toggles additional section', async ({ page }) => {
+  await page.goto('/shipping');
+
+  // "Different billing address" reveals billing fields
+  await page.getByLabel('Use different billing address').check();
+
+  const billingSection = page.getByRole('group', { name: 'Billing address' });
+  await expect(billingSection).toBeVisible();
+
+  await billingSection.getByLabel('Street').fill('456 Oak Ave');
+  await billingSection.getByLabel('City').fill('Seattle');
+
+  // Unchecking hides the section
+  await page.getByLabel('Use different billing address').uncheck();
+  await expect(billingSection).not.toBeVisible();
+});
+
+test('dependent dropdown chains', async ({ page }) => {
+  await page.goto('/location-picker');
+
+  // Country selection populates the state dropdown
+  await page.getByLabel('Country').selectOption('US');
+
+  // Wait for the dependent dropdown to be populated
+  const stateDropdown = page.getByLabel('State');
+  await expect(stateDropdown.getByRole('option')).not.toHaveCount(0);
+
+  await stateDropdown.selectOption('CA');
+
+  // State selection populates the city dropdown
+  const cityDropdown = page.getByLabel('City');
+  await expect(cityDropdown.getByRole('option')).not.toHaveCount(0);
+
+  await cityDropdown.selectOption({ label: 'Los Angeles' });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('conditional fields appear based on selection', async ({ page }) => {
+  await page.goto('/insurance/apply');
+
+  await page.getByLabel('Account type').selectOption('business');
+
+  await expect(page.getByLabel('Company name')).toBeVisible();
+  await expect(page.getByLabel('Tax ID')).toBeVisible();
+
+  await page.getByLabel('Company name').fill('Acme Corp');
+  await page.getByLabel('Tax ID').fill('12-3456789');
+
+  await page.getByLabel('Account type').selectOption('personal');
+  await expect(page.getByLabel('Company name')).not.toBeVisible();
+  await expect(page.getByLabel('Tax ID')).not.toBeVisible();
+});
+
+test('checkbox toggles additional section', async ({ page }) => {
+  await page.goto('/shipping');
+
+  await page.getByLabel('Use different billing address').check();
+
+  const billingSection = page.getByRole('group', { name: 'Billing address' });
+  await expect(billingSection).toBeVisible();
+
+  await billingSection.getByLabel('Street').fill('456 Oak Ave');
+  await billingSection.getByLabel('City').fill('Seattle');
+
+  await page.getByLabel('Use different billing address').uncheck();
+  await expect(billingSection).not.toBeVisible();
+});
+
+test('dependent dropdown chains', async ({ page }) => {
+  await page.goto('/location-picker');
+
+  await page.getByLabel('Country').selectOption('US');
+
+  const stateDropdown = page.getByLabel('State');
+  await expect(stateDropdown.getByRole('option')).not.toHaveCount(0);
+
+  await stateDropdown.selectOption('CA');
+
+  const cityDropdown = page.getByLabel('City');
+  await expect(cityDropdown.getByRole('option')).not.toHaveCount(0);
+
+  await cityDropdown.selectOption({ label: 'Los Angeles' });
+});
+```
+
+### 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.
+**Avoid when**: You only care about client-side validation. Test submission separately from validation.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('successful form submission shows confirmation', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByLabel('Name').fill('Jane Doe');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Message').fill('Hello from Playwright');
+
+  // Wait for the API response during submission
+  const responsePromise = page.waitForResponse('**/api/contact');
+  await page.getByRole('button', { name: 'Send message' }).click();
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Message sent successfully')).toBeVisible();
+});
+
+test('form submission shows server-side validation errors', async ({ page }) => {
+  await page.goto('/register');
+
+  await page.getByLabel('Email').fill('taken@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('ValidP@ss1');
+  await page.getByRole('button', { name: 'Register' }).click();
+
+  // Server responds with a 409 — email already taken
+  await expect(page.getByText('An account with this email already exists')).toBeVisible();
+});
+
+test('form shows loading state during submission', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByLabel('Name').fill('Jane');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Message').fill('Test');
+
+  await page.getByRole('button', { name: 'Send message' }).click();
+
+  // Button should be disabled during submission
+  await expect(page.getByRole('button', { name: /Sending/ })).toBeDisabled();
+
+  // After completion, button returns to normal
+  await expect(page.getByRole('button', { name: 'Send message' })).toBeEnabled();
+});
+
+test('form redirects after successful submission', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('password123');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  // Verify redirect
+  await page.waitForURL('/dashboard');
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('successful form submission shows confirmation', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByLabel('Name').fill('Jane Doe');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Message').fill('Hello from Playwright');
+
+  const responsePromise = page.waitForResponse('**/api/contact');
+  await page.getByRole('button', { name: 'Send message' }).click();
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Message sent successfully')).toBeVisible();
+});
+
+test('form submission shows server-side validation errors', async ({ page }) => {
+  await page.goto('/register');
+
+  await page.getByLabel('Email').fill('taken@example.com');
+  await page.getByLabel('Password', { exact: true }).fill('ValidP@ss1');
+  await page.getByRole('button', { name: 'Register' }).click();
+
+  await expect(page.getByText('An account with this email already exists')).toBeVisible();
+});
+
+test('form shows loading state during submission', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByLabel('Name').fill('Jane');
+  await page.getByLabel('Email').fill('jane@example.com');
+  await page.getByLabel('Message').fill('Test');
+
+  await page.getByRole('button', { name: 'Send message' }).click();
+
+  await expect(page.getByRole('button', { name: /Sending/ })).toBeDisabled();
+  await expect(page.getByRole('button', { name: 'Send message' })).toBeEnabled();
+});
+
+test('form redirects after successful submission', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('password123');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await page.waitForURL('/dashboard');
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+});
+```
+
+### Form Reset Testing
+
+**Use when**: Testing "clear form" or "reset" functionality, verifying that fields return to their default values.
+**Avoid when**: The form has no reset mechanism.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('reset button clears all fields to defaults', async ({ page }) => {
+  await page.goto('/settings');
+
+  // Change fields from defaults
+  await page.getByLabel('Display name').fill('New Name');
+  await page.getByLabel('Theme').selectOption('dark');
+  await page.getByLabel('Notifications').uncheck();
+
+  // Click reset
+  await page.getByRole('button', { name: 'Reset' }).click();
+
+  // Verify fields returned to original values
+  await expect(page.getByLabel('Display name')).toHaveValue('');
+  await expect(page.getByLabel('Theme')).toHaveValue('light');
+  await expect(page.getByLabel('Notifications')).toBeChecked();
+});
+
+test('confirmation dialog before resetting a dirty form', async ({ page }) => {
+  await page.goto('/editor');
+
+  await page.getByLabel('Title').fill('Draft post');
+
+  // Reset triggers a confirmation dialog
+  page.on('dialog', (dialog) => dialog.accept());
+  await page.getByRole('button', { name: 'Discard changes' }).click();
+
+  await expect(page.getByLabel('Title')).toHaveValue('');
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('reset button clears all fields to defaults', async ({ page }) => {
+  await page.goto('/settings');
+
+  await page.getByLabel('Display name').fill('New Name');
+  await page.getByLabel('Theme').selectOption('dark');
+  await page.getByLabel('Notifications').uncheck();
+
+  await page.getByRole('button', { name: 'Reset' }).click();
+
+  await expect(page.getByLabel('Display name')).toHaveValue('');
+  await expect(page.getByLabel('Theme')).toHaveValue('light');
+  await expect(page.getByLabel('Notifications')).toBeChecked();
+});
+
+test('confirmation dialog before resetting a dirty form', async ({ page }) => {
+  await page.goto('/editor');
+
+  await page.getByLabel('Title').fill('Draft post');
+
+  page.on('dialog', (dialog) => dialog.accept());
+  await page.getByRole('button', { name: 'Discard changes' }).click();
+
+  await expect(page.getByLabel('Title')).toHaveValue('');
+});
+```
+
+## Decision Guide
+
+| Scenario | Approach | Key API |
+|---|---|---|
+| Standard text input | `fill()` (clears, then types) | `page.getByLabel('Name').fill('Jane')` |
+| 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('Express').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('Name').type('Jane')` | `type()` appends to existing content; does not clear first | `await page.getByLabel('Name').fill('Jane')` |
+| `await page.getByLabel('Agree').click()` | `click()` toggles — if already checked, it unchecks | `await page.getByLabel('Agree').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('Jane')` | Resolves once — no retry. Race condition. | `await expect(input).toHaveValue('Jane')` |
+| 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
+// Check if it is contenteditable
+const isContentEditable = await page.getByTestId('editor').evaluate(
+  (el) => el.getAttribute('contenteditable')
+);
+
+// For contenteditable, use pressSequentially or type
+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
+// Interact with the date picker UI instead
+await page.getByLabel('Date').click();  // Opens the picker
+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
+// For custom dropdowns: click to open, then select from the listbox
+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
+// Trigger blur explicitly
+await page.getByLabel('Email').fill('invalid');
+await page.getByLabel('Email').blur();
+await expect(page.getByText('Please enter a valid email')).toBeVisible();
+
+// Or move focus to the next field
+await page.getByLabel('Password').focus();
+```
+
+## Related
+
+- [core/locators.md](locators.md) -- locator strategies for finding form elements
+- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- assertion patterns for verifying form state
+- [core/file-operations.md](file-operations.md) -- file upload fields in forms
+- [core/error-and-edge-cases.md](error-and-edge-cases.md) -- testing form error states and edge cases
+- [core/accessibility.md](accessibility.md) -- ensuring forms are accessible (label associations, ARIA attributes)
+- [core/network-mocking.md](network-mocking.md) -- mocking form submission API responses