config.yaml

A project's config.yaml tells Optics which driver to use, how to find elements, and where to write logs and results. Every setting lives in the project; there's no global config file and no environment variable that overrides it.

Run optics configure to write a working file by answering a few questions, then edit it by hand with this page.

How Optics finds the file#

We recommend one file named config.yaml at the project root, so every command reads the same settings.

Settings you leave out take their defaults. Optics ignores keys it doesn't know, so a typo such as log_levle is silently skipped.

Top-level keys#

Engine lists#

driver_sources, elements_sources, text_detection, image_detection and llm_models are lists. Each item is an engine name with its settings:

driver_sources:
  - appium:                 # engine name
      enabled: true         # required: only enabled entries are loaded
      url: "http://127.0.0.1:4723"
      capabilities:         # engine-specific settings
        platformName: Android

When several entries in one list are enabled, Optics tries them in the order you list them. For element sources this is the order in which strategies run.

An enabled entry with an unknown name fails with E0601. So does an enabled engine whose extra isn't installed. A list you write replaces the default list completely.

driver_sources#

Enable one driver. optics live refuses more than one, and optics doctor warns about it.

elements_sources#

Enable the sources that match your driver. We recommend all three for your driver: locators, page source and screenshots.

optics doctor fails a project when no enabled element source starts with the enabled driver's name.

text_detection#

image_detection#

llm_models#

llm_models:
  - gemini:
      enabled: true
      capabilities:
        model: gemini-2.5-flash

Gemini reads its credentials from the environment: GEMINI_API_KEY or GOOGLE_API_KEY, or GOOGLE_GENAI_USE_VERTEXAI=true with GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION and GOOGLE_APPLICATION_CREDENTIALS. Don't put an API key in config.yaml: Optics accepts api_key there but warns, because the file usually ends up in version control.

Examples by platform#

driver_sources:
  - appium:
      enabled: true
      url: "http://127.0.0.1:4723"        # required; the Appium server
      capabilities:                        # must not be empty
        platformName: Android              # required; picks the Android profile
        automationName: UiAutomator2
        deviceName: emulator-5554
        # udid: emulator-5554              # pin one device when several are connected
        appPackage: com.birch.shop         # the app Launch App opens
        appActivity: com.birch.shop.MainActivity
elements_sources:
  - appium_find_element: {enabled: true}   # XPath, accessibility id, class
  - appium_page_source:  {enabled: true}   # UI tree search (uses strict_element_match)
  - appium_screenshot:   {enabled: true}   # screenshots for OCR, images, self-heal
text_detection:
  - easyocr: {enabled: true}               # extra: easyocr
image_detection:
  - templatematch: {enabled: true}
log_level: INFO
file_log: true
json_log: true

driver_sources:
  - appium:
      enabled: true
      url: "http://127.0.0.1:4723"
      capabilities:
        platformName: iOS                  # picks the iOS profile
        automationName: XCUITest
        deviceName: "iPhone 15"
        bundleId: com.birch.shop           # required on iOS
        # udid: <device udid>              # for a real device
elements_sources:
  - appium_find_element: {enabled: true}
  - appium_page_source:  {enabled: true}
  - appium_screenshot:   {enabled: true}
log_level: INFO
file_log: true

driver_sources:
  - playwright:
      enabled: true                        # no url and no server
      capabilities:
        browser: chromium                  # currently ignored, see the note below
        headless: false                    # currently ignored
elements_sources:
  - playwright_find_element: {enabled: true}
  - playwright_page_source:  {enabled: true}
  - playwright_screenshot:   {enabled: true}
log_level: INFO

driver_sources:
  - selenium:
      enabled: true
      url: "http://localhost:4444/wd/hub"  # the Selenium server or Grid
      capabilities:                        # must not be empty
        browserName: chrome                # required: chrome or firefox
        browserURL: "https://birch.example"  # opened when the session starts
elements_sources:
  - selenium_find_element: {enabled: true}
  - selenium_page_source:  {enabled: true}
  - selenium_screenshot:   {enabled: true}
log_level: INFO

Appium capabilities#

Optics reads only platformName and the app id; it passes every other capability to Appium unchanged. You can write any key with the appium: prefix, for example appium:udid.

Any other platformName fails with E0104. To attach to an Appium session that's already running, add appium:existingSessionId. Optics starts a new session if it can't attach.

TV#

Android TV uses the Android example. Samsung and LG TVs use Appium's TV drivers:

driver_sources:
  - appium:
      enabled: true
      url: "http://localhost:4723"
      capabilities:
        platformName: TizenTV
        appium:automationName: TizenTV
        appium:deviceAddress: 192.168.1.50
        appium:rcToken: "14184553"
        appium:appPackage: com.birch.tv
        appium:app: /path/to/birch.wgt
        appium:chromedriverExecutableDir: /path/to/chromedrivers
elements_sources:
  - appium_page_source: {enabled: true}
  - appium_screenshot:  {enabled: true}

driver_sources:
  - appium:
      enabled: true
      url: "http://localhost:4723"
      capabilities:
        platformName: LGTV
        appium:automationName: webOS
        appium:deviceHost: 192.168.1.50
        appium:appId: com.birch.tv
elements_sources:
  - appium_screenshot: {enabled: true}

On Tizen and webOS, touch and typing keywords fail with E0105. Move around with Press Keycode and remote keys: UP, DOWN, LEFT, RIGHT, ENTER, BACK, HOME, PLAY, PAUSE, STOP, REWIND, FF. See Test TV apps.

BLE and camera#

The ble driver taps and types through a Bluetooth mouse-and-keyboard dongle. A camera or frame server provides the screen, and Optics finds elements with OCR or image templates.

driver_sources:
  - ble:
      enabled: true
      capabilities:
        device_id: "Birch test phone"     # required
        port: "/dev/ttyACM0"              # required: device path, COM port or USB product name
        pixel_width: 1080                 # the device screen in pixels
        pixel_height: 2336
        mickeys_width: 1080               # the device screen in mouse units
        mickeys_height: 2336
        x_invert: 1                       # 1 or -1
        y_invert: 1
elements_sources:
  - camera_screenshot:
      enabled: true
      capabilities:
        camera_index: 0                   # a webcam, or url: "192.168.1.20:9000" for a TCP frame server
text_detection:
  - easyocr: {enabled: true}
image_detection:
  - templatematch: {enabled: true}

The BLE driver can't launch apps, so Launch App fails. Open the app by hand or with keys before the run. XPath and text locators don't work without a UI tree; use text that OCR can read, or image templates. See Test production devices.

include and exclude#

Run a subset of test cases. There are no CLI flags for this.

include:
  - Shopper can sign in
  - Shopper can add Trail Runner 2 to the cart
# or
exclude:
  - Shopper can check out

• Names match the test_case column exactly, ignoring case.
• Set one of the two. Setting both fails with E0403.
• Test cases with "setup" or "teardown" in their names always run.

Logging#

With file_log: true and no execution_output_path, Optics also writes a copy of both logs to logs/ in the folder you ran optics from.

Values you write with the @: prefix, such as @:s3cret, are masked as **** in log files. See Read results.

ai_self_heal#

When an element can't be found, self-heal sends a screenshot to an LLM and lets it try up to five corrective steps, such as scrolling or closing a popup.

ai_self_heal: true
llm_models:
  - gemini:
      enabled: true

• It needs an enabled llm_models entry, the llm extra, Gemini credentials, and a screenshot element source such as appium_screenshot. Without them it does nothing, and the run isn't affected.
• It applies to keywords that find and act on an element: Press Element, Enter Text, Enter Number, Clear Element Text, Get Text, Swipe From Element, Scroll From Element, Detect And Press and Select Dropdown Option. It doesn't apply to assertions.
• A healed step passes. Check the logs for AI self-heal: lines so a real regression doesn't go unnoticed.

optics serve and optics mcp ignore this key. They use per-session fields and the OPTICS_AI_SELF_HEAL variable instead. See Self-heal.

strict_element_match#

strict_element_match: true

By default the page-source element sources (appium_page_source, selenium_page_source, playwright_page_source) accept close or partial text matches, so Sign in can match Sign in with email. Set strict_element_match: true to accept only exact matches. Turn it on when similar labels make tests press the wrong element.

save_captures#

save_captures: false

When false, Capture Screenshot, Capture Pagesource and Get Screen Elements stop writing files. Optics still saves the screenshot it takes before each action, the annotated screenshots and the page source logs. optics serve always turns captures off.

Starter config#

optics init writes a commented config.yaml with every engine disabled. To get started, enable one driver, enable its three element sources, and install the driver's extra with optics setup --install <name>. See Install Optics.