SurfSense/.cursor/skills/playwright-testing/testing-patterns/forms-validation.md

# Form Testing Patterns

## Table of Contents

1. [Quick Reference](#quick-reference)
2. [Patterns](#patterns)
3. [Decision Guide](#decision-guide)
4. [Anti-Patterns](#anti-patterns)
5. [Troubleshooting](#troubleshooting)

> **When to use**: Testing form filling, submission, validation messages, multi-step wizards, dynamic fields, and auto-complete interactions.

## Quick Reference

```typescript
// Text input
await page.getByLabel("Username").fill("john_doe");

// Select dropdown
await page.getByLabel("Region").selectOption("EU");
await page.getByLabel("Region").selectOption({ label: "Europe" });

// Checkbox and radio
await page.getByLabel("Subscribe").check();
await page.getByLabel("Priority shipping").click();

// Date input
await page.getByLabel("Departure").fill("2025-08-20");

// Clear a field
await page.getByLabel("Username").clear();

// Submit
await page.getByRole("button", { name: "Register" }).click();

// Verify validation error
await expect(page.getByText("Username is required")).toBeVisible();
```

## Patterns

### Auto-Complete and Typeahead Fields

**Use when**: Testing search fields, address lookups, mention pickers, or any input that shows suggestions as the user types.

```typescript
test("select from typeahead suggestions", async ({ page }) => {
  await page.goto("/products");

  const searchBox = page.getByRole("combobox", { name: "Find product" });
  await searchBox.pressSequentially("lapt", { delay: 100 });

  const suggestionList = page.getByRole("listbox");
  await expect(suggestionList).toBeVisible();

  await suggestionList.getByRole("option", { name: "Laptop Pro" }).click();
  await expect(searchBox).toHaveValue("Laptop Pro");
});

test("typeahead with API-driven suggestions", async ({ page }) => {
  await page.goto("/shipping");

  const streetField = page.getByLabel("Street");
  const responsePromise = page.waitForResponse("**/api/address-lookup*");
  await streetField.pressSequentially("456 Elm", { delay: 50 });

  await responsePromise;

  await page.getByRole("option", { name: /456 Elm St/ }).click();

  await expect(page.getByLabel("Town")).toHaveValue("Austin");
  await expect(page.getByLabel("State")).toHaveValue("TX");
  await expect(page.getByLabel("Postal code")).toHaveValue("78701");
});

test("dismiss suggestions and enter custom value", async ({ page }) => {
  await page.goto("/labels");

  const labelInput = page.getByLabel("New label");
  await labelInput.pressSequentially("my-label");

  await labelInput.press("Escape");
  await expect(page.getByRole("listbox")).not.toBeVisible();

  await labelInput.press("Enter");
  await expect(page.getByText("my-label")).toBeVisible();
});
```

### Dynamic Forms — Conditional Fields

**Use when**: Form fields appear, disappear, or change based on the value of other fields.

```typescript
test("conditional fields appear based on selection", async ({ page }) => {
  await page.goto("/loan/apply");

  await page.getByLabel("Applicant type").selectOption("corporate");

  await expect(page.getByLabel("Business name")).toBeVisible();
  await expect(page.getByLabel("EIN")).toBeVisible();

  await page.getByLabel("Business name").fill("TechCorp Inc");
  await page.getByLabel("EIN").fill("98-7654321");

  await page.getByLabel("Applicant type").selectOption("individual");
  await expect(page.getByLabel("Business name")).not.toBeVisible();
  await expect(page.getByLabel("EIN")).not.toBeVisible();
});

test("checkbox toggles additional section", async ({ page }) => {
  await page.goto("/delivery");

  await page.getByLabel("Separate invoice address").check();

  const invoiceSection = page.getByRole("group", { name: "Invoice address" });
  await expect(invoiceSection).toBeVisible();

  await invoiceSection.getByLabel("Address").fill("789 Pine Rd");
  await invoiceSection.getByLabel("City").fill("Denver");

  await page.getByLabel("Separate invoice address").uncheck();
  await expect(invoiceSection).not.toBeVisible();
});

test("dependent dropdown chains", async ({ page }) => {
  await page.goto("/region-selector");

  await page.getByLabel("Country").selectOption("CA");

  const provinceDropdown = page.getByLabel("Province");
  await expect(provinceDropdown.getByRole("option")).not.toHaveCount(0);

  await provinceDropdown.selectOption("ON");

  const cityDropdown = page.getByLabel("City");
  await expect(cityDropdown.getByRole("option")).not.toHaveCount(0);

  await cityDropdown.selectOption({ label: "Toronto" });
});
```

### Multi-Step Forms and Wizards

**Use when**: The form spans multiple pages or steps, with next/previous navigation and per-step validation.

```typescript
test("complete a multi-step booking wizard", async ({ page }) => {
  await page.goto("/booking");

  await test.step("enter guest information", async () => {
    await expect(
      page.getByRole("heading", { name: "Guest Info" }),
    ).toBeVisible();

    await page.getByLabel("Full name").fill("Alice Smith");
    await page.getByLabel("Email").fill("alice@test.com");
    await page.getByLabel("Phone").fill("555-1234");

    await page.getByRole("button", { name: "Next" }).click();
  });

  await test.step("select room options", async () => {
    await expect(
      page.getByRole("heading", { name: "Room Selection" }),
    ).toBeVisible();

    await page.getByLabel("Room type").selectOption("suite");
    await page.getByLabel("Check-in").fill("2025-09-01");
    await page.getByLabel("Check-out").fill("2025-09-05");

    await page.getByRole("button", { name: "Next" }).click();
  });

  await test.step("confirm booking", async () => {
    await expect(
      page.getByRole("heading", { name: "Confirmation" }),
    ).toBeVisible();

    await expect(page.getByText("Alice Smith")).toBeVisible();
    await expect(page.getByText("suite")).toBeVisible();

    await page.getByRole("button", { name: "Confirm booking" }).click();
  });

  await expect(
    page.getByRole("heading", { name: "Booking complete" }),
  ).toBeVisible();
});

test("wizard validates each step before proceeding", async ({ page }) => {
  await page.goto("/booking");

  await page.getByRole("button", { name: "Next" }).click();

  await expect(page.getByRole("heading", { name: "Guest Info" })).toBeVisible();
  await expect(page.getByText("Full name is required")).toBeVisible();
});

test("wizard supports going back without losing data", async ({ page }) => {
  await page.goto("/booking");

  await page.getByLabel("Full name").fill("Alice Smith");
  await page.getByLabel("Email").fill("alice@test.com");
  await page.getByLabel("Phone").fill("555-1234");
  await page.getByRole("button", { name: "Next" }).click();

  await page.getByRole("button", { name: "Previous" }).click();

  await expect(page.getByLabel("Full name")).toHaveValue("Alice Smith");
  await expect(page.getByLabel("Email")).toHaveValue("alice@test.com");
});
```

### Form Submission and Response Handling

**Use when**: Testing what happens after a form is submitted — success messages, redirects, error responses from the server, and loading states during submission.

```typescript
test("successful form submission shows confirmation", async ({ page }) => {
  await page.goto("/feedback");

  await page.getByLabel("Subject").fill("Feature request");
  await page.getByLabel("Email").fill("user@test.com");
  await page.getByLabel("Details").fill("Please add dark mode");

  const responsePromise = page.waitForResponse("**/api/feedback");
  await page.getByRole("button", { name: "Submit feedback" }).click();
  const response = await responsePromise;

  expect(response.status()).toBe(200);
  await expect(page.getByText("Feedback received")).toBeVisible();
});

test("form submission shows server-side validation errors", async ({
  page,
}) => {
  await page.goto("/signup");

  await page.getByLabel("Email").fill("existing@test.com");
  await page.getByLabel("Password", { exact: true }).fill("Secure1@pass");
  await page.getByRole("button", { name: "Sign up" }).click();

  await expect(
    page.getByText("Email address already registered"),
  ).toBeVisible();
});

test("form shows loading state during submission", async ({ page }) => {
  await page.goto("/feedback");

  await page.getByLabel("Subject").fill("Bug report");
  await page.getByLabel("Email").fill("user@test.com");
  await page.getByLabel("Details").fill("Found an issue");

  const submit = page.getByRole("button", {
    name: /Submit feedback|Submitting/,
  });
  await submit.click();

  await expect(submit).toHaveText(/Submitting/);
  await expect(submit).toBeDisabled();

  await expect(submit).toHaveText("Submit feedback");
  await expect(submit).toBeEnabled();
});

test("form redirects after successful submission", async ({ page }) => {
  await page.goto("/auth/login");

  await page.getByLabel("Email").fill("admin@test.com");
  await page.getByLabel("Password").fill("admin123");
  await page.getByRole("button", { name: "Log in" }).click();

  await page.waitForURL("/home");
  await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
});
```

### Filling Basic Form Fields

**Use when**: Testing any form with standard HTML inputs — text, email, password, number, textarea, select, checkbox, radio.

```typescript
test("fill and submit a signup form", async ({ page }) => {
  await page.goto("/signup");

  await page.getByLabel("First name").fill("Bob");
  await page.getByLabel("Last name").fill("Wilson");
  await page.getByLabel("Email").fill("bob@test.com");
  await page.getByLabel("Password", { exact: true }).fill("P@ssw0rd!");
  await page.getByLabel("Confirm password").fill("P@ssw0rd!");

  await page.getByLabel("About you").fill("Developer with 5 years experience.");
  await page.getByLabel("Years of experience").fill("5");

  await page.getByLabel("Country").selectOption("UK");
  await page.getByLabel("City").selectOption({ label: "London" });
  await page
    .getByLabel("Skills")
    .selectOption(["typescript", "playwright", "nodejs"]);

  await page.getByLabel("Accept terms").check();
  await expect(page.getByLabel("Accept terms")).toBeChecked();

  await page.getByLabel("Annual billing").check();
  await expect(page.getByLabel("Annual billing")).toBeChecked();

  await page.getByRole("button", { name: "Create account" }).click();
  await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
});
```

### Date and Time Inputs

**Use when**: Testing native `<input type="date">`, `<input type="time">`, `<input type="datetime-local">`, or third-party date pickers.

```typescript
test("fill native date and time inputs", async ({ page }) => {
  await page.goto("/reservation");

  await page.getByLabel("Reservation date").fill("2025-07-10");
  await expect(page.getByLabel("Reservation date")).toHaveValue("2025-07-10");

  await page.getByLabel("Time slot").fill("18:00");
  await page.getByLabel("Reminder").fill("2025-07-10T17:30");
});

test("interact with a third-party date picker", async ({ page }) => {
  await page.goto("/reservation");

  await page.getByLabel("Event date").click();
  await page.getByRole("button", { name: "Next month" }).click();
  await page.getByRole("gridcell", { name: "25" }).click();

  await expect(page.getByLabel("Event date")).toHaveValue(/2025/);
});
```

### Required Field Validation

**Use when**: Testing that the form shows appropriate error messages when required fields are empty.

```typescript
test("shows validation errors for empty required fields", async ({ page }) => {
  await page.goto("/inquiry");

  await page.getByRole("button", { name: "Send inquiry" }).click();

  await expect(page.getByText("Name is required")).toBeVisible();
  await expect(page.getByText("Email is required")).toBeVisible();
  await expect(page.getByText("Question is required")).toBeVisible();

  await expect(page).toHaveURL(/\/inquiry/);
});

test("clears validation errors when fields are filled", async ({ page }) => {
  await page.goto("/inquiry");

  await page.getByRole("button", { name: "Send inquiry" }).click();
  await expect(page.getByText("Name is required")).toBeVisible();

  await page.getByLabel("Name").fill("Carol Brown");
  await page.getByLabel("Email").focus();

  await expect(page.getByText("Name is required")).not.toBeVisible();
});

test("native HTML5 validation with required attribute", async ({ page }) => {
  await page.goto("/basic-form");

  await page.getByRole("button", { name: "Submit" }).click();

  const emailInput = page.getByLabel("Email");
  const validationMessage = await emailInput.evaluate(
    (el: HTMLInputElement) => el.validationMessage,
  );
  expect(validationMessage).toBeTruthy();
});
```

### Format Validation and Custom Rules

**Use when**: Testing email format, phone number format, password strength, and business-specific validation rules.

```typescript
test("validates email format", async ({ page }) => {
  await page.goto("/signup");

  const emailField = page.getByLabel("Email");

  const invalidEmails = [
    "invalid",
    "missing@",
    "@nodomain.com",
    "has spaces@mail.com",
  ];

  for (const email of invalidEmails) {
    await emailField.fill(email);
    await emailField.blur();
    await expect(page.getByText("Enter a valid email address")).toBeVisible();
  }

  await emailField.fill("correct@domain.com");
  await emailField.blur();
  await expect(page.getByText("Enter a valid email address")).not.toBeVisible();
});

test("validates password strength rules", async ({ page }) => {
  await page.goto("/signup");

  const passwordField = page.getByLabel("Password", { exact: true });

  await passwordField.fill("Xy1!");
  await passwordField.blur();
  await expect(page.getByText("Minimum 8 characters")).toBeVisible();

  await passwordField.fill("lowercase1!");
  await passwordField.blur();
  await expect(page.getByText("Include an uppercase letter")).toBeVisible();

  await passwordField.fill("SecureP@ss1");
  await passwordField.blur();
  await expect(page.getByText(/Minimum|Include/)).not.toBeVisible();
});

test("validates custom business rule — minimum amount", async ({ page }) => {
  await page.goto("/transfer");

  await page.getByLabel("Amount").fill("5");
  await page.getByLabel("Amount").blur();
  await expect(page.getByText("Minimum transfer is $10")).toBeVisible();

  await page.getByLabel("Amount").fill("1000000");
  await page.getByLabel("Amount").blur();
  await expect(page.getByText("Maximum transfer is $100,000")).toBeVisible();

  await page.getByLabel("Amount").fill("500");
  await page.getByLabel("Amount").blur();
  await expect(page.getByText(/Minimum|Maximum/)).not.toBeVisible();
});
```

### Form Reset Testing

**Use when**: Testing "clear form" or "reset" functionality, verifying that fields return to their default values.

```typescript
test("reset button clears all fields to defaults", async ({ page }) => {
  await page.goto("/preferences");

  await page.getByLabel("Nickname").fill("CustomNick");
  await page.getByLabel("Language").selectOption("es");
  await page.getByLabel("Email alerts").uncheck();

  await page.getByRole("button", { name: "Reset" }).click();

  await expect(page.getByLabel("Nickname")).toHaveValue("");
  await expect(page.getByLabel("Language")).toHaveValue("en");
  await expect(page.getByLabel("Email alerts")).toBeChecked();
});

test("confirmation dialog before resetting a dirty form", async ({ page }) => {
  await page.goto("/document");

  await page.getByLabel("Document title").fill("Draft document");

  page.on("dialog", (dialog) => dialog.accept());
  await page.getByRole("button", { name: "Clear changes" }).click();

  await expect(page.getByLabel("Document title")).toHaveValue("");
});
```

## Decision Guide

| Scenario                             | Approach                                               | Key API                                                      |
| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ |
| Standard text input                  | `fill()` (clears, then types)                          | `page.getByLabel('Field').fill('value')`                     |
| Need keystroke events (autocomplete) | `pressSequentially()` with delay                       | `locator.pressSequentially('text', { delay: 100 })`          |
| Native `<select>` dropdown           | `selectOption()` by value or label                     | `locator.selectOption('US')` or `{ label: 'United States' }` |
| Custom dropdown (ARIA listbox)       | Click trigger, then select option role                 | `getByRole('option', { name: '...' }).click()`               |
| Checkbox                             | `check()` / `uncheck()` (idempotent)                   | `locator.check()` — safe to call even if already checked     |
| Radio button                         | `check()` on the target radio                          | `page.getByLabel('Option').check()`                          |
| Date input (native)                  | `fill()` with ISO format                               | `locator.fill('2025-03-15')`                                 |
| Date picker (third-party)            | Click to open, navigate, select day                    | `getByRole('gridcell', { name: '15' }).click()`              |
| Validation errors                    | Submit, then assert error text                         | `expect(page.getByText('Required')).toBeVisible()`           |
| Multi-step wizard                    | `test.step()` per step, assert heading                 | `await test.step('Step 1', async () => { ... })`             |
| Conditional/dynamic fields           | Change trigger field, assert new field visibility      | `expect(locator).toBeVisible()` / `.not.toBeVisible()`       |
| Form submission                      | `waitForResponse` + click submit                       | Register response listener before click                      |
| Auto-complete                        | `pressSequentially()`, wait for listbox, select option | `getByRole('option', { name }).click()`                      |
| Form reset                           | Click reset, assert default values                     | `expect(locator).toHaveValue('')`                            |

## Anti-Patterns

| Don't Do This                                           | Problem                                                    | Do This Instead                                        |
| ------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| `await page.getByLabel('Field').type('value')`          | `type()` appends to existing content; does not clear first | `await page.getByLabel('Field').fill('value')`         |
| `await page.getByLabel('Option').click()`               | `click()` toggles — if already checked, it unchecks        | `await page.getByLabel('Option').check()`              |
| `await page.fill('#email', 'test@test.com')`            | CSS selector is fragile                                    | `await page.getByLabel('Email').fill('test@test.com')` |
| `await page.selectOption('select', 'US')` without label | Targets first `<select>` on page; ambiguous                | `await page.getByLabel('Country').selectOption('US')`  |
| Testing every invalid input in one test                 | Test becomes huge, slow, and hard to debug                 | One test per validation rule or group related rules    |
| `expect(await input.inputValue()).toBe('value')`        | Resolves once — no retry. Race condition.                  | `await expect(input).toHaveValue('value')`             |
| Filling fields with `page.evaluate()`                   | Bypasses event handlers (no `input`, `change` events fire) | Use `fill()` or `pressSequentially()`                  |
| Not waiting for conditional fields before filling       | `fill()` fails on hidden/detached elements                 | `await expect(field).toBeVisible()` first              |
| Hardcoding wait after selecting a dropdown              | `waitForTimeout(500)` is flaky and slow                    | Wait for the dependent element to appear               |
| Skipping server-side validation tests                   | Client-side validation can be bypassed                     | Test both client-side UX and server response           |

## Troubleshooting

### `fill()` does nothing or clears but doesn't type

**Cause**: The input field uses a contenteditable div (rich text editors), not a real `<input>` or `<textarea>`.

```typescript
const isContentEditable = await page
  .getByTestId("editor")
  .evaluate((el) => el.getAttribute("contenteditable"));

if (isContentEditable) {
  await page.getByTestId("editor").click();
  await page.getByTestId("editor").pressSequentially("Hello world");
}
```

### Date picker does not accept `fill()` value

**Cause**: Third-party date pickers often render custom UI over a hidden input. `fill()` sets the hidden input but the UI does not update.

```typescript
await page.getByLabel("Date").click();
await page.getByRole("button", { name: "Next month" }).click();
await page.getByRole("gridcell", { name: "15" }).click();

// Alternatively, if the library reads from the input on change:
await page.getByLabel("Date").fill("2025-06-15");
await page.getByLabel("Date").dispatchEvent("change");
```

### `selectOption()` throws "not a select element"

**Cause**: The dropdown is a custom component (ARIA listbox), not a native `<select>`.

```typescript
await page.getByRole("combobox", { name: "Country" }).click();
await page.getByRole("option", { name: "United States" }).click();
```

### Validation errors do not appear after `fill()` and submit

**Cause**: The validation triggers on `blur` (focus leaving the field), but `fill()` does not trigger blur automatically.

```typescript
await page.getByLabel("Email").fill("invalid");
await page.getByLabel("Email").blur();
await expect(page.getByText("Enter a valid email")).toBeVisible();

// Or move focus to the next field
await page.getByLabel("Password").focus();
```