Interaction
Choose reliable actions for clicks, input, forms, files, drag and drop, and custom controls.
Use this section when a test needs to act on the page: click, fill, type, select, upload, download, drag, scroll, or drive custom controls.
Good interactions describe what the user does. Bad interactions describe how the DOM happens to be built today.
In simple terms
Most interactions should start from a locator:
$page->getByRole('button', ['name' => 'Save'])->click();
The locator finds the user-facing target. The action waits until it is ready. The assertion proves the product state changed.
Choose your page
| Need | Open |
|---|---|
| Find the element a user would see | Locators |
| Keyboard, mouse, touch, modifiers, coordinates | Input |
| Click, fill, hover, drag, scroll | Actions |
| Inputs, validation, select boxes, custom controls | Forms |
| Uploads, downloads, file chooser, file artifacts | Files |
| Read or change page state from JavaScript | Evaluating JavaScript |
Choose the right technique
| If the user... | Prefer |
|---|---|
| clicks a visible control | locator action |
| enters text in a field | fill() |
| uses a keyboard shortcut | keyboard API |
| drags, hovers, or scrolls | action or mouse API |
| uploads a file | file input action |
| receives a generated file | download/artifact handling |
Avoid
- Clicking wrappers instead of controls.
- Filling hidden inputs instead of visible fields.
- Testing the click but not the result.
- Using CSS for buttons and labels before user-facing locators.
- Treating uploads and downloads as the same problem.
Go next
- Find the element first: Locators
- Learn actions: Actions and input
- Work with forms: Forms and controls
- Copy a flow: Fill and submit a form
- Upload a file: Upload a file
- Run an example: Drag and drop
FAQ
Should I click by CSS selector?
Only when user-facing locators are not available. Prefer role, label, text, placeholder, or test id.
When should I use keyboard or mouse APIs directly?
Use them when the sequence itself matters: shortcuts, canvas, drag behavior, hover menus, or coordinate-based widgets.
How should I test custom controls?
Assert the behavior the user sees. Do not make the test depend on private class names if the control exposes a visible option or result.