Action keywords

Action keywords do something to the app: tap, type, swipe, scroll or press a key. Each one looks at the current screen once and fails if the element isn't there. They don't wait.

module_name,module_step,param_1,param_2
Sign In,Assert Presence,${email_field},15
Sign In,Enter Text,${email_field},[email protected]
Sign In,Enter Text,${password_field},@:pw-ana
Sign In,Press Element,${sign_in}

Put an Assert Presence before an action when the screen may still be loading. For how element, index, ${name} and the aoi_* parameters work, see Keywords.

Before each action, Optics saves a screenshot to the run's output folder. See Results.

Tap#

Press Element#

Taps or clicks an element found by XPath, text, OCR or image.

Sign In,Press Element,${sign_in}
Browse,Press Element,Trail Runner 2,index=1
Checkout,Press Element,pay_button.png,aoi_y=50,aoi_height=50
Add To Cart,Press Element,${add_to_cart},event_name=tap_add_to_cart

- Press Element ${sign_in} event_name=tap_sign_in

Good to know:

• Press Element doesn't wait. If the element isn't on screen yet, the step fails.
• repeat taps several times only when the element was found in the app's UI tree, by XPath or native text. An element found by OCR or image is tapped once.
• offset_x and offset_y apply only when the element was found by OCR or image. They're ignored for elements found in the UI tree.
• When element is ${name} with several values, Optics tries each one until it finds the element.
• If self-healing is turned on, it gets one try to recover before the step fails.

Press By Percentage#

Taps a point given as a percentage of the screen width and height.

Promo,Press By Percentage,50,90
Promo,Press By Percentage,50,90,event_name=tap_banner

- Press By Percentage 50 90

Good to know:

• Values are 0–100, not 0–1. 0.5 means half a percent, which taps the edge of the screen.
• On Appium, decimals are cut off: 50.7 taps at 50 %.
• We recommend Press Element instead. A fixed point breaks when the layout changes.

Press By Coordinates#

Taps an absolute pixel coordinate on the screen.

Promo,Press By Coordinates,540,1600

- Press By Coordinates 540 1600

Good to know:

• On Appium, a failed tap is logged and the step passes. Follow it with an assertion to confirm the tap worked.
• On Selenium, Optics clicks whatever element is at that point of the page.
• To set event_name, write it by name: Press By Coordinates,540,1600,event_name=tap_promo.

Detect And Press#

Taps an element if it appears within the timeout. If it doesn't appear, the step passes without tapping.

Open Birch,Detect And Press,Allow,5
Open Birch,Detect And Press,${newsletter_close},5

- Detect And Press Allow 5

Good to know:

• Use it for pop-ups that appear only sometimes, such as permission prompts or a newsletter sign-up.
• Keep the timeout short. When the element never appears, the step waits the full timeout.
• In Python the default timeout is 10 seconds.

Select Dropdown Option#

Opens a dropdown and picks an option, scrolling inside the list if the option isn't visible.

Product,Select Dropdown Option,${size_dropdown},US 9,20

- Select Dropdown Option ${size_dropdown} "US 9" 20

Good to know:

• Optics taps the dropdown and picks the option if it's visible. Otherwise it finds the list that opened and scrolls it down half a list at a time, until the option appears or the list stops moving.
• It assumes the list opens with its first option visible.
• If the option isn't found, the error lists the options Optics did see.

Type#

Enter Text#

Types text into a field.

Search,Enter Text,${search_bar},Trail Runner 2
Search,Enter Text,${search_bar},<enter>
Sign In,Enter Text,${password_field},@:pw-ana

- Enter Text ${search_bar} "Trail Runner 2"

Good to know:

• Enter Text doesn't clear the field first. Use Clear Element Text before it if the field may have text.
• event_name comes before index here, unlike Press Element. Set index by name: index=1.
• When the field was found by OCR or image, Optics taps it, then types.
• A value that is exactly one special key in angle brackets presses that key. Appium supports <enter>, <tab>, <backspace>, <space>, <escape>, <back>, <home>, <menu>, <volumeup>, <volumedown>, <power>, <camera> and <search>. Selenium supports <enter>, <tab>, <backspace>, <space> and <escape>. An unknown name is typed literally.
• Start a value with @: to mark it as sensitive. Optics masks it as **** in log files and removes the @: before typing. Playwright doesn't remove it and types @: too.
• ${name} inside a longer value isn't replaced, so @:${password} doesn't work. Put @:pw-ana as the value in your elements file, then pass ${password}.
• In YAML, quote text that contains spaces.

Enter Number#

Types a number into a field. It works like Enter Text without special keys.

Cart,Enter Number,${quantity_field},2

- Enter Number ${quantity_field} 2

Enter Text Direct#

Types text into whichever field has focus, without looking for an element.

Search,Press Element,${search_bar}
Search,Enter Text Direct,pace knit

- Enter Text Direct "pace knit"

Good to know:

• Special keys such as <enter> aren't recognized here. They're typed as text. Use Enter Text Using Keyboard for keys.

Enter Text Using Keyboard#

Types text one key at a time, or presses one special key.

Search,Enter Text Using Keyboard,<enter>
Search,Enter Text Using Keyboard,trail runner

- Enter Text Using Keyboard <enter>

Good to know:

• Write special keys in angle brackets. enter without brackets types the word "enter".
• Use it for apps that ignore text sent all at once, such as search fields that react to each key press.

Clear Element Text#

Empties a text field.

Search,Clear Element Text,${search_bar}

- Clear Element Text ${search_bar}

Good to know:

• When the field was found by OCR or image, Optics taps it and clears it. On Playwright it selects all and deletes.

Swipe and scroll#

Directions don't all mean the same thing. For the swipe keywords and Scroll From Element on Appium, the direction is the way your finger moves: up reveals content further down. Scroll, Scroll Until Element Appears and every Playwright gesture use the page's direction instead: down reveals content further down.

Swipe#

Swipes from a pixel point in a direction.

Browse,Swipe,540,1500,up,800

- Swipe 540 1500 up 800

Good to know:

• On Appium, an unknown direction or a driver error is logged and the step passes.
• Selenium doesn't support Swipe. The step fails.
• On Playwright, Swipe scrolls the page with the mouse wheel by swipe_length pixels. down scrolls down, and every other direction scrolls up.

Swipe By Percentage#

Swipes from a point given in percent, for a distance given in percent of the screen.

Browse,Swipe By Percentage,50,80,up,40
Banner,Swipe By Percentage,90,30,left,60

- Swipe By Percentage 50 80 up 40

Good to know:

• Decimals such as 50.5 fail the step.
• Selenium doesn't support it. On Playwright it scrolls the page vertically by swipe_length percent of the window height.

Swipe From Element#

Swipes starting on an element, such as a carousel or slider.

Product,Swipe From Element,${product_carousel},left,300

- Swipe From Element ${product_carousel} left 300

Good to know:

• On Appium, driver errors during the gesture are logged and the step passes.
• Selenium doesn't support it. On Playwright, it scrolls the element's nearest scrollable area.
• In Python, direction defaults to right and swipe_length to 50.

Swipe Until Element Appears#

Swipes again and again until an element is on screen.

Browse,Swipe Until Element Appears,Pace Knit,up,30

- Swipe Until Element Appears "Pace Knit" up 30

Good to know:

• Each round checks for the element for up to 3 seconds, swipes a quarter of the screen starting near the left edge at mid-height, then waits 3 seconds.
• Selenium doesn't support it. On Playwright, use down to move down the page.
• In Python, direction defaults to down and timeout to 30.

Scroll#

Scrolls the screen once.

Browse,Scroll,down

- Scroll down

Good to know:

• On Appium, only up and down work. left and right do nothing and the step passes.
• On Appium, one scroll drags from 80 % to 20 % of the screen height.
• On Selenium, one scroll moves one window's height or width, in any of the four directions.
• On Playwright, one scroll moves about 240 pixels.
• In Python, direction defaults to down.

Scroll From Element#

Scrolls starting on an element, such as a list inside a page. It behaves the same as Swipe From Element.

Browse,Scroll From Element,${product_list},up,600

- Scroll From Element ${product_list} up 600

Good to know:

• On Appium the direction is the way your finger moves, as with Swipe From Element.
• In Python, direction defaults to down and scroll_length to 100.

Scroll Until Element Appears#

Scrolls again and again until an element is on screen.

Browse,Scroll Until Element Appears,Pace Knit,down,40

- Scroll Until Element Appears "Pace Knit" down 40

Good to know:

• Each round checks for the element for up to 3 seconds, scrolls once, then waits 3 seconds.
• If the element never appears, the step fails with error E0201.
• In Python, direction defaults to down and timeout to 30.

Keys and scripts#

Press Keycode#

Sends a hardware, system or remote-control key.

Product,Press Keycode,4
TV Browse,Press Keycode,RIGHT
TV Browse,Press Keycode,ENTER

- Press Keycode 4

Good to know:

• Selenium doesn't support it. Use Enter Text with <enter> or <tab> instead.
• On TVs, this is how you move focus and select. See TV.

Execute Script#

Runs a driver command, such as an Appium mobile: command, or JavaScript in the browser.

Device,Execute Script,"{""script"": ""mobile: pressKey"", ""args"": {""keycode"": 3}}"
Web,Execute Script,"window.scrollTo(0, 0)"

- Execute Script '{"script":"mobile: pressKey","args":{"keycode":3}}'

Good to know:

• In CSV, wrap a value that contains commas in double quotes, and double every quote inside it.
• When the value is JSON with a script key, args is passed this way: an object becomes one argument, and a list becomes one argument per item.
• The CSV and YAML runner can't store the result. It's returned over optics serve, MCP and Python.
• The BLE driver doesn't support it.

Read and wait#

Get Text#

Reads the text of an element.

Product,Get Text,//android.widget.TextView[@resource-id="com.birch.shop:id/price"]

- Get Text //android.widget.TextView[@resource-id="com.birch.shop:id/price"]

Good to know:

• The CSV and YAML runner can't store the text in a variable. To check text on screen, use Assert Presence with the text you expect.
• When the element is found only by OCR or image, Get Text returns nothing and the step still passes.
• In Python, Get Text takes element only and returns the text.

Sleep#

Waits a number of seconds.

Checkout,Sleep,3

- Sleep 3

Good to know:

• 1.5 fails the step. Use 1 or 2.
• We recommend an assertion with a timeout instead. It continues as soon as the element appears.

Deprecated#

These keywords still run but will be removed. Use the replacement shown.

Press Checkbox#

Taps an element and logs a deprecation warning. Use Press Element instead.

Checkout,Press Checkbox,${terms_checkbox}

Press Radio Button#

Taps an element and logs a deprecation warning. Use Press Element instead. It takes the same parameters as Press Checkbox.

Checkout,Press Radio Button,${express_shipping}

Swipe Seekbar To Right Android#

Meant to drag a slider to the right. It fails on Appium. Use Swipe From Element instead.

Filters,Swipe From Element,${price_slider},right,300