zebbern/claude-code-guide / skills/playwright/core
playwright-core
VerifiedBattle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.
forms-and-validation.md
View on GitHub# 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
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: 467k | 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: 467k | 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: 467k | 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: 193k | Updated | Claude CodeCodex | Verified | Install |