Test websites

Optics tests websites with one of two drivers. Playwright starts a browser on your machine and needs no server. Selenium sends commands to a WebDriver server, such as a Selenium Grid, which runs the browser.

We recommend Playwright unless you already run a Selenium Grid, or need Firefox or a real Chrome on remote machines. The examples use the Sauce Labs demo store, which you can sign in to with standard_user / secret_sauce.

Set up#

$ optics setup --install playwright

driver_sources:
  - playwright:
      enabled: true                          # no url and no server needed
      capabilities:
        browser: chromium                    # ignored on 1.10.5: always Chromium
        headless: false                      # ignored on 1.10.5: always a visible window
        # viewport: {width: 1280, height: 800}  # ignored on 1.10.5: always 1280×800
elements_sources:
  - playwright_find_element: {enabled: true}
  - playwright_page_source:  {enabled: true}
  - playwright_screenshot:   {enabled: true}

$ optics setup --install selenium

$ docker run -d -p 4444:4444 selenium/standalone-chrome

driver_sources:
  - selenium:
      enabled: true
      url: "http://localhost:4444/wd/hub"   # your Grid or standalone server
      capabilities:                          # must not be empty
        browserName: chrome                  # required: chrome or firefox
        browserURL: "https://www.saucedemo.com"  # page opened when the browser starts
elements_sources:
  - selenium_find_element: {enabled: true}
  - selenium_page_source:  {enabled: true}
  - selenium_screenshot:   {enabled: true}

Then check the setup and run your tests:

$ optics doctor my-web-tests
$ optics execute my-web-tests

Open the site#

Launch App starts the browser. How it picks the page depends on the driver:

We recommend putting the URL in the Launch App step. Then the same module works with both drivers.

Write steps for the web#

Here is a full sign-in test for the Sauce Labs demo store. It works with both drivers on Optics 1.10.5:

Element_Name,Element_ID
username_field,//input[@id='user-name']
password_field,//input[@id='password']
login_button,//input[@id='login-button']
backpack_add_button,//button[@id='add-to-cart-sauce-labs-backpack']

module_name,module_step,param_1,param_2
Open the store,Launch App,https://www.saucedemo.com
Open the store,Assert Presence,Swag Labs,15
Sign in,Press Element,${username_field}
Sign in,Enter Text Direct,standard_user
Sign in,Press Element,${password_field}
Sign in,Enter Text Direct,secret_sauce
Sign in,Press Element,${login_button}
Sign in,Assert Presence,Products,10
Add the backpack,Press Element,${backpack_add_button}
Add the backpack,Assert Presence,Remove,5

test_case,test_step
Shopper can add a backpack,Open the store
Shopper can add a backpack,Sign in
Shopper can add a backpack,Add the backpack

Locators for web pages#

We recommend XPath for web elements. It's the one kind of value that works the same way with both drivers, so you can switch drivers without editing elements.

To see an element's id or attributes, right-click it in Chrome and choose Inspect. Define elements explains each kind of value.

Press keys#

Press Keycode isn't supported on Selenium. The keys go to whichever field has focus, so press the field first.

Run in CI without a screen#

On Optics 1.10.5, Playwright always opens a visible window, even when you set headless: true. On a Linux CI machine with no display, run Optics under a virtual display:

$ xvfb-run optics execute my-web-tests

With Selenium in Docker, the browser runs inside the container, so the CI machine needs no display. To run Chrome headless on a Grid, pass Chrome's own arguments. They replace the arguments Optics adds, so keep the ones you need:

driver_sources:
  - selenium:
      enabled: true
      url: "http://localhost:4444/wd/hub"
      capabilities:
        browserName: chrome
        goog:chromeOptions:
          args: ["--headless=new", "--no-sandbox", "--disable-dev-shm-usage"]

Run tests in CI covers the rest of the CI setup.

If it isn't working#

• "Object of type Locator is not JSON serializable". Enter Text or Get Text ran in Playwright on 1.10.5. Use Press Element, then Enter Text Direct. See Troubleshooting.
• The Playwright browser isn't installed. Run optics setup --install playwright again. optics doctor shows a ✅ for playwright browser once Chromium is downloaded.
• "Selenium capabilities not found in config". Add browserName: chrome or browserName: firefox under capabilities.
• "Cannot start" with "No Selenium/WebDriver server reachable". Start the server, and check that url points to it.
• Swipe fails on Selenium. Selenium has no Swipe. Use Scroll, which moves one screen in any direction.
• A step acts before the page loads. Actions don't wait. Put Assert Presence on something from the new page before you act on it.
• **A password typed in Playwright starts with @:.** Playwright doesn't strip the secret prefix. Leave it off for Playwright.

See also#

• Write your first test
• Define elements
• Run tests in CI
• Actions reference
• config.yaml reference