Project files

An Optics project is a folder of CSV or YAML files plus a config.yaml. This page lists every file format Optics reads, the exact columns and keys, and what a run writes back.

For a guided introduction, see Write a test and Write tests in YAML.

How Optics finds your files#

Optics walks the whole project folder, including subfolders, and decides what each .csv, .yml and .yaml file is by its content, not its name or location. You can use any folder layout. We recommend the one optics init creates:

birch-tests/
├── config.yaml
├── test_cases/test_cases.csv
├── modules/modules.csv
├── test_data/elements.csv
└── test_data/error_definitions.csv    # optional

A project needs at least one test cases file and one modules file. Elements, error definitions and API files are optional. You can split each type across several files.

When two files define the same thing:

• Test cases and modules with the same name: the file read last wins, with a warning in the log.
• Elements with the same name: the values are combined into one fallback list.

Image files (.png, .jpg, .jpeg, .bmp) anywhere in the project are available as image templates by file name. If two images share a name, one of them is used.

Test cases#

Each row adds one step to a test case. A step names a module. Rows run in order, and a test case can span rows anywhere in the file.

test_case,test_step
Suite Setup,Open Birch
Shopper can sign in,Sign In
Shopper can sign in,Check Home Screen
Shopper can add a shoe,Search For Trail Runner
Shopper can add a shoe,Add To Cart
Suite Teardown,Close Birch

Test Cases:
  - Suite Setup:
      - Open Birch
  - Shopper can sign in:
      - Sign In
      - Check Home Screen
  - Shopper can add a shoe:
      - Search For Trail Runner
      - Add To Cart
  - Suite Teardown:
      - Close Birch

Within a test case, the first failing step fails the test case and skips its remaining steps. The next test case still runs.

Setup and teardown#

Optics treats some test case names specially. Matching ignores case and looks for the words anywhere in the name.

We recommend Suite Setup and Suite Teardown, which work as expected. Avoid per-test Setup and Teardown until this is fixed; open and close the app inside each test case's own modules if you need that.

• A failing setup doesn't stop the test cases after it.
• Test cases whose names contain "setup" or "teardown" always run, even when include or exclude would skip them.
• Don't use "setup" or "teardown" in an ordinary test name. "Setup wizard works" is treated as the per-test setup.

Modules#

Each row is one keyword step. A module is the rows that share a module_name, in order.

module_name,module_step,param_1,param_2,param_3
Open Birch,Launch App,,,
Sign In,Assert Presence,${email_field},20,
Sign In,Enter Text,${email_field},[email protected],
Sign In,Enter Text,${password_field},@:s3cret,
Sign In,Press Element,${sign_in},,
Search For Trail Runner,Press Element,${search_bar},,
Search For Trail Runner,Enter Text,${search_bar},Trail Runner 2,
Add To Cart,Press Element,${add_to_cart},index=0,
Close Birch,Close And Terminate App,,,

Modules:
  - Open Birch:
      - Launch App
  - Sign In:
      - Assert Presence ${email_field} 20
      - Enter Text ${email_field} [email protected]
      - Enter Text ${password_field} @:s3cret
      - Press Element ${sign_in}
  - Search For Trail Runner:
      - Press Element ${search_bar}
      - Enter Text ${search_bar} "Trail Runner 2"
  - Add To Cart:
      - Press Element ${add_to_cart} index=0
  - Close Birch:
      - Close And Terminate App

Parameter rules:

• Empty cells are dropped, and the values after them move left. You can't skip a parameter by leaving its cell blank. Use a named parameter instead.
• Named parameters are written name=value, for example index=0 or timeout_str=20. They work only when name is a real parameter of that keyword. Anything else, such as text=Sign in or css=#search, stays a positional value.
• Variables written as a whole cell, ${email_field}, are replaced with the element's values. Hello ${name} isn't substituted; Optics types it as written.
• Values starting with /, // or ( are always positional, so XPaths are never mistaken for named parameters.

In YAML, a step is one string. The keyword name is matched first, and the rest is split on spaces. Wrap a value with spaces in quotes: "Trail Runner 2". Wrap multi-word module names you pass as parameters in quotes too: Run Loop "Add To Cart" 3.

See Keywords for each keyword's parameters.

Elements#

Each row gives a name to a locator or a value. Steps refer to it as ${name}.

Element_Name,Element_ID,Element_ID_text,Element_ID_image
email_field,//android.widget.EditText[@resource-id='com.birch.shop:id/email'],Email,
password_field,//android.widget.EditText[@resource-id='com.birch.shop:id/password'],Password,
sign_in,//android.widget.Button[@text='Sign in'],Sign in,sign_in.png
search_bar,//*[@resource-id='com.birch.shop:id/search'],Search,
add_to_cart,text=Add to cart,,add_to_cart.png
order_total,placeholder,,

Elements:
  email_field:
    - //android.widget.EditText[@resource-id='com.birch.shop:id/email']
    - Email
  sign_in: ["//android.widget.Button[@text='Sign in']", "Sign in", "sign_in.png"]
  search_bar: "//*[@resource-id='com.birch.shop:id/search']"
  add_to_cart: ["text=Add to cart", "add_to_cart.png"]
  order_total: placeholder

• Empty cells are ignored. Columns that don't start with Element_ID, such as Element_Text, are ignored.
• A second row with the same name adds more fallback values.
• When a step uses ${name}, Optics tries each value in turn until the step passes, up to 20 attempts. It moves on only when the element isn't found. Steps inside Run Loop, Condition and Execute Module use only the first value.
• Variables a step creates while running, such as the target of Evaluate or Read Data, need a row with a placeholder value so optics dry_run passes.

Optics decides what kind of locator a value is from its form:

Text like (optional) or Size [US] is read as XPath or CSS. Add text= in front to force text: text=Size [US]. See Define elements.

Error definitions#

A CSV file of messages that mean your app is in a bad state. At the end of optics execute, Optics checks the text on the final screen against each match_string.

error_code,match_string,description,severity
BIRCH_001,Unfortunately,App crashed with a system dialog,critical
BIRCH_002,Something went wrong,Birch showed its generic error screen,high
BIRCH_003,Out of stock,Product page shows out of stock,medium

There's no YAML form. A match adds a failing test case to junit_output.xml but doesn't change the exit code. See Detect on-screen errors.

API definitions#

A YAML file with a top-level api: key defines HTTP calls that the Invoke API keyword makes. You can also put the api: block inside config.yaml.

api:
  collections:
    birch:                                  # collection id, used in Invoke API
      name: Birch API
      base_url: https://api.birch.example
      global_headers:
        Accept: application/json
      apis:
        get_product:                        # API id
          name: Get product
          description: Look up Trail Runner 2
          endpoint: /v1/products/trail-runner-2
          request:
            method: GET
            headers: {}
            body: null
          expected_result:
            jsonpath_assertions:
              - path: $.name
                condition: "$ == 'Trail Runner 2'"
            extract:
              product_price: $.price        # saves ${product_price}

Call it from a module with Invoke API,birch.get_product. Only the top-level key api works; a file whose top key is apis is recognized but loads nothing. See Call an API.

Escaping and special values#

CSV quoting. Wrap a cell in double quotes when it contains a comma, and double any quotes inside it:

module_name,module_step,param_1
Find Shoe,Press Element,"//*[contains(@text,'Trail Runner 2')]"
Go Home,Execute Script,"{""script"": ""mobile: pressKey"", ""args"": {""keycode"": 3}}"

Backslash sequences. In any cell, \n becomes a new line, \t a tab, \r a carriage return, and \\ a single backslash.

Secrets. Start a value with @:, as in @:s3cret, to mask it as **** in log files. Appium, Selenium and BLE remove the prefix before typing. Playwright types the prefix too.

Encoding. Save files as UTF-8. Some spreadsheet apps add a byte order mark (BOM) at the start of the file, which can stop Optics recognizing the header row.

YAML quoting. A quoted value that contains = keeps its quotes. Write conditions without spaces instead: Condition ${size}=='9' "Pick Size" "Show Error".

Outputs#

optics execute and optics dry_run write to execution_output/ in the project, unless you set execution_output_path in config.yaml.

birch-tests/execution_output/
├── junit_output.xml
├── logs.json                                      # json_log: true
├── internal_logs.log                              # file_log: true
├── execution_logs.log                             # file_log: true
├── 2026-10-09T15-04-05-123456-pre_press_element.jpg
├── ...-press_element_element_detection_result.jpg
├── ...-end_of_run.jpg
├── page_sources_log.xml
└── detected_errors_<session_id>.json              # only when error definitions match

Screenshots are JPEG files named <timestamp>-<name>.jpg. The detection-result screenshots use a timestamp with colons in it, which Windows doesn't allow in file names, so they may be missing on Windows.

optics live writes elsewhere: screenshots/session_<time>/ and logs/optics_live_<time>.log in the project. See Read results.