# Optics documentation

> Every page of the Optics docs, as Markdown. Append .md to any docs URL for the same thing.

- [Docs home](https://optics-framework.org/docs/index.md): where to start, by goal and by level.

## Get started

- [Get started with Optics](https://optics-framework.org/docs/get-started/index.md): Learn what Optics does, what it tests, and the fastest way to see it run.
- [Run your first test](https://optics-framework.org/docs/get-started/quickstart.md): Install Optics and run a working test in a browser in about five minutes.
- [Install Optics](https://optics-framework.org/docs/get-started/install.md): Install the optics command, then add only the drivers and engines your platform needs.
- [Write your first test](https://optics-framework.org/docs/get-started/first-test.md): Build a test from scratch that signs in to an online store and adds a product to the cart.
- [How Optics works](https://optics-framework.org/docs/get-started/concepts.md): Learn the five ideas every Optics test is built from, and what happens when a test runs.
- [What to learn next](https://optics-framework.org/docs/get-started/next-steps.md): Pick your next page based on what you want Optics to do for you.

## Create tests

- [Choose how to create tests](https://optics-framework.org/docs/create/index.md): Learn which way of creating tests fits your team. Every way produces the same files.
- [Write a test suite](https://optics-framework.org/docs/create/write.md): Write test cases, modules and elements by hand, in CSV or YAML.
- [Record a test](https://optics-framework.org/docs/create/record.md): Build a test by running steps one at a time against the live app, then save the ones that worked.
- [Describe a test in plain English](https://optics-framework.org/docs/create/describe.md): Tell Optics what to do in a sentence, let an AI model drive the app, and keep the steps it took.
- [Let your AI agent build tests](https://optics-framework.org/docs/create/agent.md): Connect Optics to Claude, Cursor or any MCP client so your agent can drive a device and write the suite.
- [Use Optics from Python](https://optics-framework.org/docs/create/python.md): Call Optics keywords from pytest or any Python script when a test needs real code.
- [Use Optics in Robot Framework](https://optics-framework.org/docs/create/robot.md): Import Optics as a Robot Framework library and use its keywords in .robot files.
- [Organise a suite](https://optics-framework.org/docs/create/organise.md): Structure a growing suite with setup and teardown, shared modules, several files and run selection.
- [Write tests in YAML](https://optics-framework.org/docs/create/yaml.md): Keep a whole flow in one indented file, and learn the quoting rules that make YAML steps work.

## Find elements

- [How Optics finds elements](https://optics-framework.org/docs/elements/index.md): Learn how Optics tries several ways to find each element, so one changed locator doesn't fail a test.
- [Define elements](https://optics-framework.org/docs/elements/define.md): Name the things your tests touch, choose good values for them, and add fallbacks that survive redesigns.
- [Find elements by text and image](https://optics-framework.org/docs/elements/text-and-images.md): Use OCR and image matching to find elements the UI tree can't see, such as text inside images, canvases and video.
- [Search part of the screen](https://optics-framework.org/docs/elements/area-of-interest.md): Limit where Optics looks for an element, so repeated text can't be matched in the wrong place and vision runs faster.
- [Recover failing steps with AI self-heal](https://optics-framework.org/docs/elements/self-heal.md): Let an AI model look at the screen and finish a step when every way of finding its element has failed.

## Run and report

- [Run a suite](https://optics-framework.org/docs/run/index.md): Check a suite without a device, run it for real, and choose which test cases run.
- [Read the results](https://optics-framework.org/docs/run/results.md): Find out what happened in a run from the JUnit report, the screenshots and the logs.
- [Catch error screens](https://optics-framework.org/docs/run/error-detection.md): Fail a run in CI when the app ends on a crash dialog, a "Session expired" message or any other error you define.
- [Run tests in CI](https://optics-framework.org/docs/run/ci.md): Run the same suite on every pull request and read the results in your CI system.
- [Readiness checklist](https://optics-framework.org/docs/run/checklist.md): Use this checklist before you rely on a suite in CI or for production monitoring.

## Platforms

- [Supported platforms](https://optics-framework.org/docs/platforms/index.md): Learn which platforms Optics drives, what each one needs, and which keywords behave differently.
- [Test Android apps](https://optics-framework.org/docs/platforms/android.md): Set up Appium and adb, then run your tests on an Android phone or emulator.
- [Test iOS apps](https://optics-framework.org/docs/platforms/ios.md): Set up Appium with the XCUITest driver, then run your tests on an iOS simulator or device.
- [Test websites](https://optics-framework.org/docs/platforms/web.md): Set up Playwright or Selenium, then run your tests in a browser.
- [Test TV apps](https://optics-framework.org/docs/platforms/tv.md): Drive Android TV, Samsung Tizen and LG webOS apps with remote-control keys.
- [Test production devices](https://optics-framework.org/docs/platforms/production.md): Test locked devices and live apps through a Bluetooth mouse and keyboard and a camera.

## Advanced

- [Advanced](https://optics-framework.org/docs/advanced/index.md): Add data, logic and integrations to your suites once the basics are in place.
- [Variables](https://optics-framework.org/docs/advanced/variables.md): Store values, compute new ones during a run, and use them in later steps.
- [Run a flow with different data](https://optics-framework.org/docs/advanced/data-driven.md): Repeat one module for every value in a list, such as each user, search term or product.
- [Conditions and loops](https://optics-framework.org/docs/advanced/conditions.md): Run different modules depending on what's on screen or in a variable, and handle optional screens such as popups.
- [Call APIs in a test](https://optics-framework.org/docs/advanced/api-calls.md): Call an HTTP API in the middle of a test, check the response, and use values from it in later steps.
- [Run keywords over HTTP](https://optics-framework.org/docs/advanced/http-api.md): Start a local Optics server and drive a device or browser from your own service, one keyword per request.
- [Generate pytest or Robot code](https://optics-framework.org/docs/advanced/generate.md): Turn a CSV or YAML suite into a pytest or Robot Framework file you can extend with code.

## Reference

- [Reference](https://optics-framework.org/docs/reference/index.md): Look up every command, setting, file format and keyword.
- [Keywords](https://optics-framework.org/docs/reference/keywords/index.md): Every keyword you can use in a step, grouped by what it does.
- [App management keywords](https://optics-framework.org/docs/reference/keywords/app.md): Learn how to start, switch, close and inspect the app or browser under test.
- [Action keywords](https://optics-framework.org/docs/reference/keywords/actions.md): Learn how to tap, type, swipe, scroll and send keys in a step.
- [Verification keywords](https://optics-framework.org/docs/reference/keywords/verification.md): Learn which keyword to use for each check, and how long each one waits.
- [Flow control keywords](https://optics-framework.org/docs/reference/keywords/flow.md): Learn how to reuse modules, loop, branch, load data, compute values and call APIs in a suite.
- [CLI](https://optics-framework.org/docs/reference/cli.md): Look up every `optics` command, its flags, what it writes and the exit codes it returns.
- [config.yaml](https://optics-framework.org/docs/reference/config.md): Every setting in a project's config.yaml.
- [Project files](https://optics-framework.org/docs/reference/files.md): The file formats Optics reads: test cases, modules, elements, error definitions and API definitions.
- [Engines and extras](https://optics-framework.org/docs/reference/engines.md): Learn which drivers, element sources, OCR, image matching and LLM engines Optics supports, and which pip extra installs each one.
- [MCP server](https://optics-framework.org/docs/reference/mcp.md): Tools and resources that `optics mcp` gives your AI agent.
- [HTTP API](https://optics-framework.org/docs/reference/http-api.md): Learn the endpoints `optics serve` exposes for starting sessions, running keywords and streaming results.
- [Error codes](https://optics-framework.org/docs/reference/errors.md): Learn what each Optics error code means and how to fix it.

## Help

- [Get help](https://optics-framework.org/docs/help/index.md): Find the answer to a problem yourself, or report it so someone else can.
- [Troubleshooting](https://optics-framework.org/docs/help/troubleshooting.md): Fix the most common problems with installing, configuring and running Optics.
- [Frequently asked questions](https://optics-framework.org/docs/help/faq.md): Learn what Optics can and can't do, with short answers to the questions people ask most.
- [Glossary](https://optics-framework.org/docs/help/glossary.md): Learn the terms used across the Optics docs.