Playwright 08 ๐ญ Page Interactions โ Clicking, Typing, Selecting, and Hovering
Playwright’s interaction methods are the actions that drive the page: click, fill, type, select, hover, check, and press. Every action runs the actionability checks before it executes, and every action returns a Promise that must be awaited. The difference between fill and type, between click and dblclick, and between selectOption and check is the event sequence each produces, and the event sequence is what determines whether the application’s handler fires.
This chapter covers the core interaction methods, the event sequences they produce, and the modifier and option arguments that control their behavior. The sections that follow walk through clicking and typing, selecting and checking, and the keyboard and hover interactions that do not fit the click-and-type pattern.
Key point: fill sets the value in one event; type sends a keypress per character; click runs the actionability checks and then clicks; selectOption fires the change event; each method produces the event sequence a real user would, and the application’s handler depends on that sequence.
a. Clicking and the click variants
locator.click() runs the actionability checks and then dispatches a mousedown, mouseup, and click at the element’s center. The options control the button, the click count, the modifiers, and the position.
import { test, expect } from "@playwright/test";
test("clicks the primary button", async ({ page }) => {
await page.goto("/");
// Default: left button, center, single click
await page.getByRole("button", { name: "Submit" }).click();
// Right click
await page.getByRole("button", { name: "Menu" }).click({ button: "right" });
// Double click
await page.getByText("File").dblclick();
// With modifier
await page.getByRole("link", { name: "Docs" }).click({ modifiers: ["Control"] });
// Force: skip the actionability checks
await page.getByRole("button", { name: "Hidden" }).click({ force: true });
});
The force: true option is the one that bypasses the checks. It skips the visible, stable, receives-events, and enabled checks, and clicks the element even if it is covered or hidden. It is the escape hatch for a test that genuinely needs to click a non-actionable element, and it should not be the default: the checks are the reason the click waits for the page to be ready.
The click with a position option clicks at a specific point inside the element. The trial: true option runs the actionability checks without performing the click, which is useful for asserting that an element is clickable.
// Click at the top-left corner of the element
await locator.click({ position: { x: 5, y: 5 } });
// Run the checks without clicking
await locator.click({ trial: true });
The dblclick is a separate method rather than a clickCount: 2 option, although the option exists. The dblclick produces the double-click event sequence the browser expects.
b. Typing and filling
fill sets the value of an input in one event. It focuses the element, clears the current value, and sets the new value, and it dispatches an input event. It does not send a keypress per character, which makes it fast and deterministic for a value that the test already knows.
// Set the value in one event
await page.getByLabel("Email").fill("user@example.com");
// Clear the input
await page.getByLabel("Email").fill("");
type sends a keydown, keypress, and keyup for each character. It is slower, and it is the correct method when the application listens to individual keystrokesโan autocomplete, a search-as-you-type input, a masked field that formats the value on each key.
// Send each character as a keypress
await page.getByLabel("Search").type("playwright", { delay: 50 });
// Press a key without typing
await page.getByLabel("Search").press("Enter");
The delay option adds a pause between characters, which is useful for a debounced input that would otherwise miss the intermediate values. The press method sends a single key or key combination, and it is the method for Enter, Tab, Escape, and the arrow keys.
The clear method clears the input without setting a new value, and the inputValue method reads the current value. The fill method is the default for a text field; type is for the fields that need the keystroke sequence.
c. Selecting, checking, and hovering
selectOption selects an option in a <select> element. The argument can be the option’s value, its label, its index, or an object with the value, label, or index property.
// By value
await page.getByLabel("Country").selectOption("us");
// By label
await page.getByLabel("Country").selectOption({ label: "United States" });
// By index
await page.getByLabel("Country").selectOption({ index: 1 });
// Multiple values
await page.getByLabel("Tags").selectOption(["a", "b"]);
check and uncheck are the methods for checkboxes and radio buttons. check ensures the element is checked, and it is idempotent: a second check on an already-checked box does nothing. click on a checkbox toggles it, which means a click on an already-checked box unchecks it; check is the method that expresses the intent.
// Ensure checked
await page.getByLabel("Remember me").check();
// Ensure unchecked
await page.getByLabel("Remember me").uncheck();
// Assert the state
await expect(page.getByLabel("Remember me")).toBeChecked();
hover moves the mouse over the element and triggers the mouseover and mouseenter events. It is the method for a menu that opens on hover, a tooltip, or a CSS :hover state.
await page.getByRole("button", { name: "Menu" }).hover();
await expect(page.getByRole("menu")).toBeVisible();
The dragTo method performs a drag from one element to another. It is the method for a drag-and-drop interaction, and it runs the actionability checks on both elements.
Complete Example Session
// ============================================
// PART 1: CLICK VARIANTS
// ============================================
import { test, expect } from "@playwright/test";
test("clicks the button", async ({ page }) => {
await page.goto("/");
await page.getByRole("button", { name: "Submit" }).click();
await expect(page.getByText("Saved")).toBeVisible();
});
// ============================================
// PART 2: FILL VS TYPE
// ============================================
test("fills and types", async ({ page }) => {
await page.goto("/");
// Fast, one event
await page.getByLabel("Email").fill("user@example.com");
// Keystroke per character, for autocomplete
await page.getByLabel("Search").type("playwright", { delay: 50 });
// Press a key
await page.getByLabel("Search").press("Enter");
});
// ============================================
// PART 3: SELECT
// ============================================
test("selects a country", async ({ page }) => {
await page.goto("/");
await page.getByLabel("Country").selectOption({ label: "United States" });
await expect(page.getByLabel("Country")).toHaveValue("us");
});
// ============================================
// PART 4: CHECK
// ============================================
test("checks the checkbox", async ({ page }) => {
await page.goto("/");
await page.getByLabel("Remember me").check();
await expect(page.getByLabel("Remember me")).toBeChecked();
});
// ============================================
// PART 5: HOVER
// ============================================
test("opens the menu on hover", async ({ page }) => {
await page.goto("/");
await page.getByRole("button", { name: "Menu" }).hover();
await expect(page.getByRole("menu")).toBeVisible();
});
The parts covered the click variants, the fill-versus-type distinction, the select, the check, and the hover.
Quick Reference
Click Variants
| Method | Event Sequence |
|---|---|
click() | mousedown, mouseup, click |
dblclick() | Two click sequences |
click({ button: "right" }) | Right button |
click({ modifiers: ["Control"] }) | With modifier |
click({ force: true }) | Skip checks |
Text Input
| Method | Behavior |
|---|---|
fill(value) | One event, fast |
type(value, { delay }) | Keystroke per character |
press(key) | Single key |
clear() | Clear the value |
Selection and State
| Method | Target |
|---|---|
selectOption(v) | <select> |
check() | Checkbox, radio |
uncheck() | Checkbox, radio |
hover() | Mouse over |
dragTo(target) | Drag and drop |
Best Practices
โ Do This:
// Use fill for known values
await page.getByLabel("Email").fill("a@b.com"); // โ
// Use type for autocomplete
await page.getByLabel("Search").type("play", { delay: 50 }); // โ
// Use check for checkboxes
await page.getByLabel("Terms").check(); // โ
// Let the checks run
await page.getByRole("button").click(); // โ
โ Don’t Do This:
// Use type for a known value
await page.getByLabel("Email").type("a@b.com"); // slow // โ
// Use click on a checkbox to check it
await page.getByLabel("Terms").click(); // toggles // โ
// Force the click without a reason
await locator.click({ force: true }); // skips checks // โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Autocomplete misses the value | fill used | Use type with delay |
| Checkbox toggles back | click used | Use check() |
| Click does nothing | Hydration not complete | Disable until hydrated |
Select does not fire change | Wrong method | Use selectOption |
Real-World Examples
1. Click
await page.getByRole("button", { name: "Submit" }).click();
2. Fill
await page.getByLabel("Email").fill("a@b.com");
3. Type with delay
await page.getByLabel("Search").type("play", { delay: 50 });
4. Press Enter
await page.getByLabel("Search").press("Enter");
5. Select by label
await page.getByLabel("Country").selectOption({ label: "United States" });
6. Check
await page.getByLabel("Terms").check();
7. Hover
await page.getByRole("button", { name: "Menu" }).hover();
8. Right click
await page.getByRole("button").click({ button: "right" });
9. Modifier click
await page.getByRole("link").click({ modifiers: ["Control"] });
10. Trial click
await locator.click({ trial: true });
Visual
Fill vs Type
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ fill("abc") โ
โ โ focus, clear, set value, input event โ
โ โ one event sequence โ
โ โ
โ type("abc", { delay: 50 }) โ
โ โ keydown/keypress/keyup for "a" โ
โ โ 50ms โ
โ โ keydown/keypress/keyup for "b" โ
โ โ 50ms โ
โ โ keydown/keypress/keyup for "c" โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Click Event Sequence
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ locator.click() โ
โ โ โ
โ โผ โ
โ Actionability checks โ
โ โ โ
โ โผ โ
โ mousedown โ
โ โ โ
โ โผ โ
โ mouseup โ
โ โ โ
โ โผ โ
โ click โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Check vs Click
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ check() โ
โ โ ensures checked โ
โ โ idempotent โ
โ โ
โ click() โ
โ โ toggles โ
โ โ a second click unchecks โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Force Click
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ click() โ
โ โ visible, stable, receives events, enabled โ
โ โ
โ click({ force: true }) โ
โ โ skips the checks โ
โ โ clicks even if covered or hidden โ
โ โ
โ Use only when the element is genuinely not actionable โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Click | locator.click() |
| Double click | locator.dblclick() |
| Fill | locator.fill(value) |
| Type | locator.type(value, { delay }) |
| Press | locator.press(key) |
| Select | locator.selectOption(...) |
| Check | locator.check() |
| Hover | locator.hover() |
| Force | click({ force: true }) skips checks |
Key takeaways:
- Every action runs the actionability checks. The click waits for the element to be visible, stable, able to receive events, and enabled. The
force: trueoption skips the checks and should be the exception, not the default. fillis one event;typeis a keystroke per character. Usefillfor a known value andtypefor an autocomplete or a masked field that reacts to each key.checkis idempotent;clicktoggles. A checkbox that should be checked ischeck(), because a second call does nothing. Aclickon an already-checked box unchecks it.selectOptionfires thechangeevent. It is the method for a<select>, and it accepts the value, the label, or the index.hovertriggers the mouse events. It is the method for a menu that opens on hover and a tooltip, and it runs the actionability checks like the other actions.
Remember: The interaction methods produce the event sequences a real user would. fill sets the value, type presses the keys, click dispatches the mouse events, and check ensures the state. The method choice determines which handler the application receives, so a test that uses fill on an autocomplete or click on a checkbox is testing a different interaction than the one the user performs.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!