# 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