Actions
Click, type, press keys, choose options and scroll with real input, and know what Retest checks first.
Every action is real input. A click presses and releases the mouse, and a fill types the text. The page hears the same trusted events a person would give it.
The actions Link to The actions
| Action | What it does |
|---|---|
page.goto(url) | Opens a URL and waits for the load event. A relative URL opens on the app's base URL. |
page.reload(), page.goBack(), page.goForward() | Moves as the browser's own buttons do, and waits for the page. |
locator.click() | Presses the mouse at the element's centre. On a touch screen it taps. |
locator.hover() | Moves the mouse to the element's centre. |
locator.tap() | Taps the element's centre. Only an app whose every target has a touch screen has it. |
locator.fill(value) | Focuses a text field, selects its value and types the new one. The value is text or a secret(). |
locator.press(key) | Focuses the element and presses one key or one shortcut on it. |
page.keyboard.press(key) | Presses one key or one shortcut on whatever has the focus. |
locator.select(choice) | Chooses options of a <select> with the keyboard, by label or by { value }. |
locator.check(), locator.uncheck() | Ticks or unticks a checkbox, a radio button or an element with a checkable role. |
locator.scroll({ x, y }), page.scroll({ x, y }) | Turns the mouse wheel at the element's centre, or at the centre of the viewport. |
await page.goto('/settings')await page.getByLabel('Name').fill('Ada')await page.getByLabel('Priority').select({ value: 'high' })await page.getByLabel('Newsletter').check()await page.getByLabel('Search').press('Enter')await page.keyboard.press('ControlOrMeta+K')What Retest checks first Link to What Retest checks first
Retest looks at the element just before it acts. When a check does not pass, the action waits and looks again until its time runs out.
| Action | The element must be |
|---|---|
click, select, check, uncheck, locator.scroll | Visible, stable, enabled and not covered |
hover | Visible, stable and not covered. A disabled element can be hovered. |
press | Attached, visible and enabled, and it keeps the focus once Retest focuses it |
page.keyboard.press, page.scroll | Nothing: they act on whatever has the focus, or on the page |
Enabled here means the native disabled state. An element that only aria-disabled marks can still be clicked.
The guard Link to The guard
A guard in the page watches the input itself. If the press, the release or the click lands on another element, Retest stops the event before any listener hears it. The action fails not_actionable and names the element that took it.
- While the browser opens another document, no action starts. Retest waits for the document and looks for the element there.
- Typing that reaches a document that replaced the one Retest checked is stopped there, and the fill fails.
- When Retest cannot see where the input went, as when a frame covers the element, the action ends
outcome_unknown. - An input that may have been sent is never sent again.
Keys Link to Keys
press takes one key, with modifiers when the test names them:
- A named key:
Enter,Tab,Escape,Backspace,Delete,Space,ArrowUp,ArrowDown,ArrowLeft,ArrowRight,Home,End,PageUporPageDown. - One character, such as
a,?oré. Retest presses the key that types it on a US keyboard, with Shift for an uppercase letter. - Modifiers and a key, joined by
+, as inShift+TaborMeta+Shift+Z. The modifiers areShift,Control,Alt,MetaandControlOrMeta, which is Meta on macOS and Control elsewhere.
A misspelt key, such as press('Entr'), is a type error. Enter in a form field submits the form once.
Choose, tick and scroll Link to Choose, tick and scroll
selecttakes a label,{ value }, or a list of them for a<select multiple>. Each choice must match exactly one option. When the select already holds the choice, nothing is sent.checkon a control that is already ticked sends nothing. Otherwise it clicks once and reads the control until it is ticked. A hidden checkbox with one visible label is clicked through its label.scrollsends one wheel event with the whole distance, in CSS pixels. Every action already brings its element into view, so scroll only for what the page does on scroll.
Time limits Link to Time limits
goto and every action take { timeout } in milliseconds, as in click({ timeout: 2000 }). It can shorten the action's budget, never lengthen it. An action has 10 seconds by default. goto, reload, goBack and goForward have 30.
A JavaScript dialog fails the command as unsupported, and downloads are denied in every context Retest opens.