Record a test

optics live opens an interactive session next to your device or browser. You type a step, Optics runs it straight away, and you see whether it worked. Every step that succeeds is recorded. When the flow is done, /save writes it into your suite as a module, ready for optics execute.

Before you begin#

You need a project with a working config.yaml that has exactly one driver enabled. Any project from optics quickstart or the first test tutorial works. For a phone, start the Appium server and your emulator first. See Android or iOS.

Start a session#

$ optics live birch-tests

Leave out the folder to use the current one. Optics opens the app straight away (it runs launch_app for you), so the first line of the session is already a recorded step.

The screen has three parts:

  ✓ launch_app
     1.21s
  ✓ enter_text ${email_field} [email protected]
     0.48s  [XPath]
─────────────────────────────────────────────────────────────────
› press_element "Sign in"
─────────────────────────────────────────────────────────────────
appium:emulator-5554  ·  rec ●  ·  /help · /quit · Tab complete · Ctrl-K keywords · Ctrl-N AI mode

• History, at the top: each step with ✓ or ✗, how long it took, and how the element was found ([XPath], [Text], [OCR] or [Image]).
• Input, in the middle: where you type.
• Status bar, at the bottom: the device or browser you're connected to, and rec ● to show recording is on.

Run steps#

Type a keyword and its values, separated by spaces, and press Enter:

› enter_text ${email_field} [email protected]
› enter_text ${password_field} "correct horse"
› press_element "Sign in"
› assert_presence "Picked for you"

• Write keyword names in snake_case or in words: press_element, Press Element and press element all work.
• Put quotes around a value that contains spaces.
• Type ${ to pick from the elements already defined in your project.
• Press Tab to complete a keyword name. The rest of its parameters appear in grey as a hint.
• Press Ctrl+K to browse every keyword.

If a step fails, it's shown with ✗ and the reason, and it isn't recorded. Try a different value and run it again. Only steps that work end up in your test.

Save the recording#

When the flow works, save it with a test case name and a module name:

› /save Checkout Sign_In
  • Saved 4 step(s) → module 'Sign_In' in modules/modules.csv, test case 'Checkout' in test_cases/test_cases.csv

Optics then:

• appends the steps to modules/modules.csv as the module Sign_In,
• adds a Checkout,Sign_In row to test_cases/test_cases.csv,
• copies the session's screenshots to execution_output/Sign_In/,
• clears the recording, so the next steps you run become the next module.

Run more steps, then /save Checkout Add_To_Cart to add a second module to the same test case.

/save writes the steps exactly as you typed them. If you typed press_element "Sign in", the module uses the text Sign in. To use a named element instead, type ${sign_in}, or edit modules.csv afterwards and add the element to elements.csv. /save always writes CSV, even in a project that uses YAML.

Commands and keys#

On Android, plugging in a new phone during a session switches to it automatically and opens the app.

Where files go#

If it isn't working#

• "optics live needs a config.yaml…": run it from a project folder, or pass the folder: optics live my_project.
• "optics live supports exactly one enabled driver": set enabled: false on every driver in config.yaml except one.
• **Every step fails with "run launch_app first"**: the app didn't open. Check that the Appium server is running and the device is connected (optics doctor my_project), then type launch_app.

See also#

• Describe a test in plain English
• Write a test suite
• Keyword reference