1# Form Testing Patterns
2 
3## Table of Contents
4 
51. [Quick Reference](#quick-reference)
62. [Patterns](#patterns)
73. [Decision Guide](#decision-guide)
84. [Anti-Patterns](#anti-patterns)
95. [Troubleshooting](#troubleshooting)
10 
11> **When to use**: Testing form filling, submission, validation messages, multi-step wizards, dynamic fields, and auto-complete interactions.
12 
13## Quick Reference
14 
15```typescript
16// Text input
17await page.getByLabel("Username").fill("john_doe");
18 
19// Select dropdown
20await page.getByLabel("Region").selectOption("EU");
21await page.getByLabel("Region").selectOption({ label: "Europe" });
22 
23// Checkbox and radio
24await page.getByLabel("Subscribe").check();
25await page.getByLabel("Priority shipping").click();
26 
27// Date input
28await page.getByLabel("Departure").fill("2025-08-20");
29 
30// Clear a field
31await page.getByLabel("Username").clear();
32 
33// Submit
34await page.getByRole("button", { name: "Register" }).click();
35 
36// Verify validation error
37await expect(page.getByText("Username is required")).toBeVisible();
38```
39 
40## Patterns
41 
42### Auto-Complete and Typeahead Fields
43 
44**Use when**: Testing search fields, address lookups, mention pickers, or any input that shows suggestions as the user types.
45 
46```typescript
47test("select from typeahead suggestions", async ({ page }) => {
48  await page.goto("/products");
49 
50  const searchBox = page.getByRole("combobox", { name: "Find product" });
51  await searchBox.pressSequentially("lapt", { delay: 100 });
52 
53  const suggestionList = page.getByRole("listbox");
54  await expect(suggestionList).toBeVisible();
55 
56  await suggestionList.getByRole("option", { name: "Laptop Pro" }).click();
57  await expect(searchBox).toHaveValue("Laptop Pro");
58});
59 
60test("typeahead with API-driven suggestions", async ({ page }) => {
61  await page.goto("/shipping");
62 
63  const streetField = page.getByLabel("Street");
64  const responsePromise = page.waitForResponse("**/api/address-lookup*");
65  await streetField.pressSequentially("456 Elm", { delay: 50 });
66 
67  await responsePromise;
68 
69  await page.getByRole("option", { name: /456 Elm St/ }).click();
70 
71  await expect(page.getByLabel("Town")).toHaveValue("Austin");
72  await expect(page.getByLabel("State")).toHaveValue("TX");
73  await expect(page.getByLabel("Postal code")).toHaveValue("78701");
74});
75 
76test("dismiss suggestions and enter custom value", async ({ page }) => {
77  await page.goto("/labels");
78 
79  const labelInput = page.getByLabel("New label");
80  await labelInput.pressSequentially("my-label");
81 
82  await labelInput.press("Escape");
83  await expect(page.getByRole("listbox")).not.toBeVisible();
84 
85  await labelInput.press("Enter");
86  await expect(page.getByText("my-label")).toBeVisible();
87});
88```
89 
90### Dynamic Forms — Conditional Fields
91 
92**Use when**: Form fields appear, disappear, or change based on the value of other fields.
93 
94```typescript
95test("conditional fields appear based on selection", async ({ page }) => {
96  await page.goto("/loan/apply");
97 
98  await page.getByLabel("Applicant type").selectOption("corporate");
99 
100  await expect(page.getByLabel("Business name")).toBeVisible();
101  await expect(page.getByLabel("EIN")).toBeVisible();
102 
103  await page.getByLabel("Business name").fill("TechCorp Inc");
104  await page.getByLabel("EIN").fill("98-7654321");
105 
106  await page.getByLabel("Applicant type").selectOption("individual");
107  await expect(page.getByLabel("Business name")).not.toBeVisible();
108  await expect(page.getByLabel("EIN")).not.toBeVisible();
109});
110 
111test("checkbox toggles additional section", async ({ page }) => {
112  await page.goto("/delivery");
113 
114  await page.getByLabel("Separate invoice address").check();
115 
116  const invoiceSection = page.getByRole("group", { name: "Invoice address" });
117  await expect(invoiceSection).toBeVisible();
118 
119  await invoiceSection.getByLabel("Address").fill("789 Pine Rd");
120  await invoiceSection.getByLabel("City").fill("Denver");
121 
122  await page.getByLabel("Separate invoice address").uncheck();
123  await expect(invoiceSection).not.toBeVisible();
124});
125 
126test("dependent dropdown chains", async ({ page }) => {
127  await page.goto("/region-selector");
128 
129  await page.getByLabel("Country").selectOption("CA");
130 
131  const provinceDropdown = page.getByLabel("Province");
132  await expect(provinceDropdown.getByRole("option")).not.toHaveCount(0);
133 
134  await provinceDropdown.selectOption("ON");
135 
136  const cityDropdown = page.getByLabel("City");
137  await expect(cityDropdown.getByRole("option")).not.toHaveCount(0);
138 
139  await cityDropdown.selectOption({ label: "Toronto" });
140});
141```
142 
143### Multi-Step Forms and Wizards
144 
145**Use when**: The form spans multiple pages or steps, with next/previous navigation and per-step validation.
146 
147```typescript
148test("complete a multi-step booking wizard", async ({ page }) => {
149  await page.goto("/booking");
150 
151  await test.step("enter guest information", async () => {
152    await expect(
153      page.getByRole("heading", { name: "Guest Info" }),
154    ).toBeVisible();
155 
156    await page.getByLabel("Full name").fill("Alice Smith");
157    await page.getByLabel("Email").fill("[email protected]");
158    await page.getByLabel("Phone").fill("555-1234");
159 
160    await page.getByRole("button", { name: "Next" }).click();
161  });
162 
163  await test.step("select room options", async () => {
164    await expect(
165      page.getByRole("heading", { name: "Room Selection" }),
166    ).toBeVisible();
167 
168    await page.getByLabel("Room type").selectOption("suite");
169    await page.getByLabel("Check-in").fill("2025-09-01");
170    await page.getByLabel("Check-out").fill("2025-09-05");
171 
172    await page.getByRole("button", { name: "Next" }).click();
173  });
174 
175  await test.step("confirm booking", async () => {
176    await expect(
177      page.getByRole("heading", { name: "Confirmation" }),
178    ).toBeVisible();
179 
180    await expect(page.getByText("Alice Smith")).toBeVisible();
181    await expect(page.getByText("suite")).toBeVisible();
182 
183    await page.getByRole("button", { name: "Confirm booking" }).click();
184  });
185 
186  await expect(
187    page.getByRole("heading", { name: "Booking complete" }),
188  ).toBeVisible();
189});
190 
191test("wizard validates each step before proceeding", async ({ page }) => {
192  await page.goto("/booking");
193 
194  await page.getByRole("button", { name: "Next" }).click();
195 
196  await expect(page.getByRole("heading", { name: "Guest Info" })).toBeVisible();
197  await expect(page.getByText("Full name is required")).toBeVisible();
198});
199 
200test("wizard supports going back without losing data", async ({ page }) => {
201  await page.goto("/booking");
202 
203  await page.getByLabel("Full name").fill("Alice Smith");
204  await page.getByLabel("Email").fill("[email protected]");
205  await page.getByLabel("Phone").fill("555-1234");
206  await page.getByRole("button", { name: "Next" }).click();
207 
208  await page.getByRole("button", { name: "Previous" }).click();
209 
210  await expect(page.getByLabel("Full name")).toHaveValue("Alice Smith");
211  await expect(page.getByLabel("Email")).toHaveValue("[email protected]");
212});
213```
214 
215### Form Submission and Response Handling
216 
217**Use when**: Testing what happens after a form is submitted — success messages, redirects, error responses from the server, and loading states during submission.
218 
219```typescript
220test("successful form submission shows confirmation", async ({ page }) => {
221  await page.goto("/feedback");
222 
223  await page.getByLabel("Subject").fill("Feature request");
224  await page.getByLabel("Email").fill("[email protected]");
225  await page.getByLabel("Details").fill("Please add dark mode");
226 
227  const responsePromise = page.waitForResponse("**/api/feedback");
228  await page.getByRole("button", { name: "Submit feedback" }).click();
229  const response = await responsePromise;
230 
231  expect(response.status()).toBe(200);
232  await expect(page.getByText("Feedback received")).toBeVisible();
233});
234 
235test("form submission shows server-side validation errors", async ({
236  page,
237}) => {
238  await page.goto("/signup");
239 
240  await page.getByLabel("Email").fill("[email protected]");
241  await page.getByLabel("Password", { exact: true }).fill("Secure1@pass");
242  await page.getByRole("button", { name: "Sign up" }).click();
243 
244  await expect(
245    page.getByText("Email address already registered"),
246  ).toBeVisible();
247});
248 
249test("form shows loading state during submission", async ({ page }) => {
250  await page.goto("/feedback");
251 
252  await page.getByLabel("Subject").fill("Bug report");
253  await page.getByLabel("Email").fill("[email protected]");
254  await page.getByLabel("Details").fill("Found an issue");
255 
256  const submit = page.getByRole("button", {
257    name: /Submit feedback|Submitting/,
258  });
259  await submit.click();
260 
261  await expect(submit).toHaveText(/Submitting/);
262  await expect(submit).toBeDisabled();
263 
264  await expect(submit).toHaveText("Submit feedback");
265  await expect(submit).toBeEnabled();
266});
267 
268test("form redirects after successful submission", async ({ page }) => {
269  await page.goto("/auth/login");
270 
271  await page.getByLabel("Email").fill("[email protected]");
272  await page.getByLabel("Password").fill("admin123");
273  await page.getByRole("button", { name: "Log in" }).click();
274 
275  await page.waitForURL("/home");
276  await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
277});
278```
279 
280### Filling Basic Form Fields
281 
282**Use when**: Testing any form with standard HTML inputs — text, email, password, number, textarea, select, checkbox, radio.
283 
284```typescript
285test("fill and submit a signup form", async ({ page }) => {
286  await page.goto("/signup");
287 
288  await page.getByLabel("First name").fill("Bob");
289  await page.getByLabel("Last name").fill("Wilson");
290  await page.getByLabel("Email").fill("[email protected]");
291  await page.getByLabel("Password", { exact: true }).fill("P@ssw0rd!");
292  await page.getByLabel("Confirm password").fill("P@ssw0rd!");
293 
294  await page.getByLabel("About you").fill("Developer with 5 years experience.");
295  await page.getByLabel("Years of experience").fill("5");
296 
297  await page.getByLabel("Country").selectOption("UK");
298  await page.getByLabel("City").selectOption({ label: "London" });
299  await page
300    .getByLabel("Skills")
301    .selectOption(["typescript", "playwright", "nodejs"]);
302 
303  await page.getByLabel("Accept terms").check();
304  await expect(page.getByLabel("Accept terms")).toBeChecked();
305 
306  await page.getByLabel("Annual billing").check();
307  await expect(page.getByLabel("Annual billing")).toBeChecked();
308 
309  await page.getByRole("button", { name: "Create account" }).click();
310  await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
311});
312```
313 
314### Date and Time Inputs
315 
316**Use when**: Testing native `<input type="date">`, `<input type="time">`, `<input type="datetime-local">`, or third-party date pickers.
317 
318```typescript
319test("fill native date and time inputs", async ({ page }) => {
320  await page.goto("/reservation");
321 
322  await page.getByLabel("Reservation date").fill("2025-07-10");
323  await expect(page.getByLabel("Reservation date")).toHaveValue("2025-07-10");
324 
325  await page.getByLabel("Time slot").fill("18:00");
326  await page.getByLabel("Reminder").fill("2025-07-10T17:30");
327});
328 
329test("interact with a third-party date picker", async ({ page }) => {
330  await page.goto("/reservation");
331 
332  await page.getByLabel("Event date").click();
333  await page.getByRole("button", { name: "Next month" }).click();
334  await page.getByRole("gridcell", { name: "25" }).click();
335 
336  await expect(page.getByLabel("Event date")).toHaveValue(/2025/);
337});
338```
339 
340### Required Field Validation
341 
342**Use when**: Testing that the form shows appropriate error messages when required fields are empty.
343 
344```typescript
345test("shows validation errors for empty required fields", async ({ page }) => {
346  await page.goto("/inquiry");
347 
348  await page.getByRole("button", { name: "Send inquiry" }).click();
349 
350  await expect(page.getByText("Name is required")).toBeVisible();
351  await expect(page.getByText("Email is required")).toBeVisible();
352  await expect(page.getByText("Question is required")).toBeVisible();
353 
354  await expect(page).toHaveURL(/\/inquiry/);
355});
356 
357test("clears validation errors when fields are filled", async ({ page }) => {
358  await page.goto("/inquiry");
359 
360  await page.getByRole("button", { name: "Send inquiry" }).click();
361  await expect(page.getByText("Name is required")).toBeVisible();
362 
363  await page.getByLabel("Name").fill("Carol Brown");
364  await page.getByLabel("Email").focus();
365 
366  await expect(page.getByText("Name is required")).not.toBeVisible();
367});
368 
369test("native HTML5 validation with required attribute", async ({ page }) => {
370  await page.goto("/basic-form");
371 
372  await page.getByRole("button", { name: "Submit" }).click();
373 
374  const emailInput = page.getByLabel("Email");
375  const validationMessage = await emailInput.evaluate(
376    (el: HTMLInputElement) => el.validationMessage,
377  );
378  expect(validationMessage).toBeTruthy();
379});
380```
381 
382### Format Validation and Custom Rules
383 
384**Use when**: Testing email format, phone number format, password strength, and business-specific validation rules.
385 
386```typescript
387test("validates email format", async ({ page }) => {
388  await page.goto("/signup");
389 
390  const emailField = page.getByLabel("Email");
391 
392  const invalidEmails = [
393    "invalid",
394    "missing@",
395    "@nodomain.com",
396    "has [email protected]",
397  ];
398 
399  for (const email of invalidEmails) {
400    await emailField.fill(email);
401    await emailField.blur();
402    await expect(page.getByText("Enter a valid email address")).toBeVisible();
403  }
404 
405  await emailField.fill("[email protected]");
406  await emailField.blur();
407  await expect(page.getByText("Enter a valid email address")).not.toBeVisible();
408});
409 
410test("validates password strength rules", async ({ page }) => {
411  await page.goto("/signup");
412 
413  const passwordField = page.getByLabel("Password", { exact: true });
414 
415  await passwordField.fill("Xy1!");
416  await passwordField.blur();
417  await expect(page.getByText("Minimum 8 characters")).toBeVisible();
418 
419  await passwordField.fill("lowercase1!");
420  await passwordField.blur();
421  await expect(page.getByText("Include an uppercase letter")).toBeVisible();
422 
423  await passwordField.fill("SecureP@ss1");
424  await passwordField.blur();
425  await expect(page.getByText(/Minimum|Include/)).not.toBeVisible();
426});
427 
428test("validates custom business rule — minimum amount", async ({ page }) => {
429  await page.goto("/transfer");
430 
431  await page.getByLabel("Amount").fill("5");
432  await page.getByLabel("Amount").blur();
433  await expect(page.getByText("Minimum transfer is $10")).toBeVisible();
434 
435  await page.getByLabel("Amount").fill("1000000");
436  await page.getByLabel("Amount").blur();
437  await expect(page.getByText("Maximum transfer is $100,000")).toBeVisible();
438 
439  await page.getByLabel("Amount").fill("500");
440  await page.getByLabel("Amount").blur();
441  await expect(page.getByText(/Minimum|Maximum/)).not.toBeVisible();
442});
443```
444 
445### Form Reset Testing
446 
447**Use when**: Testing "clear form" or "reset" functionality, verifying that fields return to their default values.
448 
449```typescript
450test("reset button clears all fields to defaults", async ({ page }) => {
451  await page.goto("/preferences");
452 
453  await page.getByLabel("Nickname").fill("CustomNick");
454  await page.getByLabel("Language").selectOption("es");
455  await page.getByLabel("Email alerts").uncheck();
456 
457  await page.getByRole("button", { name: "Reset" }).click();
458 
459  await expect(page.getByLabel("Nickname")).toHaveValue("");
460  await expect(page.getByLabel("Language")).toHaveValue("en");
461  await expect(page.getByLabel("Email alerts")).toBeChecked();
462});
463 
464test("confirmation dialog before resetting a dirty form", async ({ page }) => {
465  await page.goto("/document");
466 
467  await page.getByLabel("Document title").fill("Draft document");
468 
469  page.on("dialog", (dialog) => dialog.accept());
470  await page.getByRole("button", { name: "Clear changes" }).click();
471 
472  await expect(page.getByLabel("Document title")).toHaveValue("");
473});
474```
475 
476## Decision Guide
477 
478| Scenario                             | Approach                                               | Key API                                                      |
479| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ |
480| Standard text input                  | `fill()` (clears, then types)                          | `page.getByLabel('Field').fill('value')`                     |
481| Need keystroke events (autocomplete) | `pressSequentially()` with delay                       | `locator.pressSequentially('text', { delay: 100 })`          |
482| Native `<select>` dropdown           | `selectOption()` by value or label                     | `locator.selectOption('US')` or `{ label: 'United States' }` |
483| Custom dropdown (ARIA listbox)       | Click trigger, then select option role                 | `getByRole('option', { name: '...' }).click()`               |
484| Checkbox                             | `check()` / `uncheck()` (idempotent)                   | `locator.check()` — safe to call even if already checked     |
485| Radio button                         | `check()` on the target radio                          | `page.getByLabel('Option').check()`                          |
486| Date input (native)                  | `fill()` with ISO format                               | `locator.fill('2025-03-15')`                                 |
487| Date picker (third-party)            | Click to open, navigate, select day                    | `getByRole('gridcell', { name: '15' }).click()`              |
488| Validation errors                    | Submit, then assert error text                         | `expect(page.getByText('Required')).toBeVisible()`           |
489| Multi-step wizard                    | `test.step()` per step, assert heading                 | `await test.step('Step 1', async () => { ... })`             |
490| Conditional/dynamic fields           | Change trigger field, assert new field visibility      | `expect(locator).toBeVisible()` / `.not.toBeVisible()`       |
491| Form submission                      | `waitForResponse` + click submit                       | Register response listener before click                      |
492| Auto-complete                        | `pressSequentially()`, wait for listbox, select option | `getByRole('option', { name }).click()`                      |
493| Form reset                           | Click reset, assert default values                     | `expect(locator).toHaveValue('')`                            |
494 
495## Anti-Patterns
496 
497| Don't Do This                                           | Problem                                                    | Do This Instead                                        |
498| ------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
499| `await page.getByLabel('Field').type('value')`          | `type()` appends to existing content; does not clear first | `await page.getByLabel('Field').fill('value')`         |
500| `await page.getByLabel('Option').click()`               | `click()` toggles — if already checked, it unchecks        | `await page.getByLabel('Option').check()`              |
501| `await page.fill('#email', '[email protected]')`            | CSS selector is fragile                                    | `await page.getByLabel('Email').fill('[email protected]')` |
502| `await page.selectOption('select', 'US')` without label | Targets first `<select>` on page; ambiguous                | `await page.getByLabel('Country').selectOption('US')`  |
503| Testing every invalid input in one test                 | Test becomes huge, slow, and hard to debug                 | One test per validation rule or group related rules    |
504| `expect(await input.inputValue()).toBe('value')`        | Resolves once — no retry. Race condition.                  | `await expect(input).toHaveValue('value')`             |
505| Filling fields with `page.evaluate()`                   | Bypasses event handlers (no `input`, `change` events fire) | Use `fill()` or `pressSequentially()`                  |
506| Not waiting for conditional fields before filling       | `fill()` fails on hidden/detached elements                 | `await expect(field).toBeVisible()` first              |
507| Hardcoding wait after selecting a dropdown              | `waitForTimeout(500)` is flaky and slow                    | Wait for the dependent element to appear               |
508| Skipping server-side validation tests                   | Client-side validation can be bypassed                     | Test both client-side UX and server response           |
509 
510## Troubleshooting
511 
512### `fill()` does nothing or clears but doesn't type
513 
514**Cause**: The input field uses a contenteditable div (rich text editors), not a real `<input>` or `<textarea>`.
515 
516```typescript
517const isContentEditable = await page
518  .getByTestId("editor")
519  .evaluate((el) => el.getAttribute("contenteditable"));
520 
521if (isContentEditable) {
522  await page.getByTestId("editor").click();
523  await page.getByTestId("editor").pressSequentially("Hello world");
524}
525```
526 
527### Date picker does not accept `fill()` value
528 
529**Cause**: Third-party date pickers often render custom UI over a hidden input. `fill()` sets the hidden input but the UI does not update.
530 
531```typescript
532await page.getByLabel("Date").click();
533await page.getByRole("button", { name: "Next month" }).click();
534await page.getByRole("gridcell", { name: "15" }).click();
535 
536// Alternatively, if the library reads from the input on change:
537await page.getByLabel("Date").fill("2025-06-15");
538await page.getByLabel("Date").dispatchEvent("change");
539```
540 
541### `selectOption()` throws "not a select element"
542 
543**Cause**: The dropdown is a custom component (ARIA listbox), not a native `<select>`.
544 
545```typescript
546await page.getByRole("combobox", { name: "Country" }).click();
547await page.getByRole("option", { name: "United States" }).click();
548```
549 
550### Validation errors do not appear after `fill()` and submit
551 
552**Cause**: The validation triggers on `blur` (focus leaving the field), but `fill()` does not trigger blur automatically.
553 
554```typescript
555await page.getByLabel("Email").fill("invalid");
556await page.getByLabel("Email").blur();
557await expect(page.getByText("Enter a valid email")).toBeVisible();
558 
559// Or move focus to the next field
560await page.getByLabel("Password").focus();
561```
562