Keywords

A keyword is one action or check, such as Press Element or Assert Presence. Each row of a module is one keyword followed by its parameters. This page covers the rules every keyword shares, then lists all of them.

module_name,module_step,param_1,param_2
Sign In,Enter Text,${email_field},[email protected]
Sign In,Press Element,${sign_in}
Sign In,Assert Presence,Welcome,20

Keyword names#

Write keyword names in Title Case in CSV and YAML files: Press Element, Assert Presence. In optics live, the MCP server and Python, the same keyword is written in snake_case: press_element, assert_presence.

The runner ignores capitalization and collapses spaces, so Press Element, press element and press_element all reach the same keyword. If you misspell a name, the error suggests the closest match. Run optics list to print every keyword name in snake_case.

Parameters#

Parameters are positional. They fill the keyword's parameters in the order shown in each parameter table on these pages.

To set a parameter by name, write name=value. This works only when name is a real parameter of that keyword. Use it to skip parameters you want to leave at their defaults:

Browse,Press Element,Trail Runner 2,index=1

Here index=1 sets the fifth parameter of Press Element and leaves repeat, offset_x and offset_y at their defaults.

A value like text=Sign in or css=#cart stays positional, because text and css aren't parameter names. Values that start with /, // or ( are never treated as named, and ==, !=, <= and >= don't count as =.

Every value is a string#

Each keyword receives its parameters as text and converts them itself. Timeouts, counts, index, repeat, lengths and swipe percentages must be whole numbers. A decimal such as 2.5 fails the step. Timeouts are always in seconds.

Element arguments#

Many keywords take an element. Optics looks at the text you pass and decides what kind of locator it is. The checks run in this order, and the first match wins:

Text is matched against the app's UI tree first, then with OCR if you configured text detection. Image file names are matched by file name only, and Optics finds the file anywhere in your project folder. See Text and images for how matching works.

Other pitfalls:

• id: locators always fail. No element source supports them. Use an XPath such as //*[@resource-id="com.birch.shop:id/cart"].
• The text= prefix is understood by the Appium and Playwright element sources. OCR and Selenium search for the whole value, including text=, so use it only where you need it.
• The xpath= prefix works only on Playwright. Use a bare //… XPath on Appium and Selenium.
• .tif and .tiff files aren't treated as images. Save templates as .png.

Most of the time you pass ${name} instead and define the locator in your elements file. See Define elements.

Variables#

A cell that is exactly ${name} is replaced with the value of name from your elements file, or from a keyword that wrote it (Read Data, Evaluate, Run Loop, Invoke API).

When an element has several values, Optics tries each one in order until the element is found. It moves on only when the element isn't found. Any other error fails the step at once. If name isn't defined anywhere, the step fails before the keyword runs.

See Variables for how values are stored and passed between steps.

Areas of interest#

Keywords that find one element take four optional parameters: aoi_x, aoi_y, aoi_width and aoi_height. They limit the search to a rectangle of the screen, in percent from 0 to 100. The defaults 0, 0, 100, 100 mean the whole screen.

Checkout,Press Element,Pay now,aoi_y=50,aoi_height=50

This searches the bottom half of the screen only. Assertion keywords don't take an area of interest. See Area of interest.

Picking one of several matches#

index picks which match to use when more than one element matches. It starts at 0, the first match. index=1 is the second match.

• Image matches are counted top to bottom, then left to right.
• On Appium, index doesn't apply to XPath. Write (//android.widget.Button[@text="Add to cart"])[2] to pick the second XPath match. XPath counts from 1.
• On Selenium, a non-zero index skips the native lookup, so only OCR and image matching can use it.

Event names#

Most action and app keywords take an optional event_name. When you set it, Optics records a timestamped event with that label right before the action. Events show in the live console and are sent to an events endpoint if you configured one. They never change whether a step passes.

Action keywords don't wait#

Press Element, Enter Text and the other action keywords look at the current screen once. If the element isn't there yet, the step fails at once. Put an assertion before an action when the screen may still be loading:

Search,Assert Presence,${search_bar},15
Search,Enter Text,${search_bar},Trail Runner 2

Use Detect And Press for pop-ups that may or may not appear. Assertion keywords are the only ones that wait. See Verification keywords.

Keywords that never fail a step#

These keywords pass even when you might expect a failure. Don't rely on them as checks.

• Assert Equality returns false on a mismatch but never fails.
• Validate Screen returns false when nothing is found but never fails.
• Detect And Press passes and skips the tap when the element doesn't appear.
• Force Terminate App on Appium logs any error and passes.
• Swipe, Press By Coordinates and Scroll on Appium log driver errors and pass. Scroll left or right on Appium does nothing and passes.
• Assert Presence and Assert Visibility pass without checking when every element you give is a CSS selector, an id: locator or a class name.
• Initialise Setup does nothing.

Keywords that return a value, such as Get Text, Execute Script and Capture Screenshot, can't store it in a variable from CSV or YAML. The value is returned to you over optics serve, MCP and Python.

All keywords#

App management#

Actions#

Verification#

Flow control#

Deprecated keywords#

Press Checkbox and Press Radio Button still work but log a warning. Use Press Element instead. Swipe Seekbar To Right Android fails on Appium. Use Swipe From Element instead.

Where each keyword works#

• **CSV and YAML suites, optics live and optics serve** have every keyword on this page.
• The MCP server has every keyword except the flow-control ones. Press By Coordinates and Press By Percentage are hidden there unless you turn them on.
• Python and Robot Framework have every keyword except Execute Module, Initialise Setup and the three deprecated ones. Some parameters differ. See Write tests in Python.
• **optics generate** skips flow-control keywords and a few others when it converts a suite to code.

Python and Robot Framework only#

These keywords exist only in the Python library and the Robot Framework library. The CSV and YAML runner reports them as unknown keywords.