Exit course
Chapter 3 of 10 Beginner 6 min read 2 quick checks Updated

Your first Robot Framework test with SeleniumLibrary

On this page
  1. The test file
  2. Run it
  3. Locators
  4. Waiting: Should versus Wait Until
  5. Running headless
  6. Screenshots on failure

This chapter writes one test against the Selenium practice web form, runs it, reads the log, and then breaks it in two instructive ways: once by checking too early, and once by running headless.

The test file#

Create tests/first.robot:

*** Settings ***
Documentation     A first browser test with SeleniumLibrary.
Library           SeleniumLibrary

*** Test Cases ***
Submit The Web Form
    Open Browser    https://www.selenium.dev/selenium/web/web-form.html    chrome
    Title Should Be    Web form
    Input Text    id:my-text-id    Robot Framework
    Select From List By Label    name:my-select    Two
    Click Button    css:button[type=submit]
    Wait Until Page Contains    Received!
    [Teardown]    Close Browser

A .robot file is split into sections, each opened by a header with three asterisks:

  • *** Settings *** imports libraries and resource files and sets suite-wide options such as setup and teardown.
  • *** Variables *** defines variables (next chapter).
  • *** Test Cases *** holds the tests. A line that starts in the first column is a test name; the indented lines below it are its steps.
  • *** Keywords *** holds your own keywords (next chapter).

[Teardown] is a test setting: the keyword after it runs when the test ends, whether it passed or failed. If you put Close Browser as an ordinary last step instead, a failure in any earlier step skips it and leaves a browser running.

Run it#

robot --outputdir results tests/first.robot
==============================================================================
First :: A first browser test with SeleniumLibrary.
==============================================================================
Submit The Web Form                                                   | PASS |
------------------------------------------------------------------------------
First :: A first browser test with SeleniumLibrary.                   | PASS |
1 test, 1 passed, 0 failed
==============================================================================
Output:  /home/you/robot-course/results/output.xml
Log:     /home/you/robot-course/results/log.html
Report:  /home/you/robot-course/results/report.html

The suite name, First, comes from the file name. A Chrome window opens, the form is filled and submitted, and the window closes. Without --outputdir the three result files land in the current folder; keeping them in results/ (and in .gitignore) saves a lot of clutter.

Open results/log.html. It shows every keyword the test called, with its arguments, its duration and what it logged. When a test fails, this file is where you start: chapter 8 covers it in detail.

Locators#

SeleniumLibrary keywords that act on an element take a locator. The prefix before the colon picks the strategy:

Locator Finds
id:my-text-id the element with that id
name:my-select by name attribute, typical for form fields
css:button[type=submit] by CSS selector
xpath://button[text()="Submit"] by XPath
link:Return to index a link by its exact text

Without a prefix, SeleniumLibrary tries id and name, and treats a value starting with // as XPath. Write the prefix anyway: it states your intent and avoids surprises when an id and a name collide.

Prefer locators that describe what the element is (an id, a name, a data-test attribute) over ones that describe where it happens to sit, such as xpath://div[3]/form/div[2]/button. The second kind breaks on the first layout change.

A test calls Close Browser as its last step. When an earlier step fails, Chrome windows pile up on the CI agent. What is the fix?

A failing step ends the test body immediately, so later steps never run. A teardown always runs. Ignoring every error would hide the real failure and make the test pass when it should not.

Waiting: Should versus Wait Until#

SeleniumLibrary keywords come in two families:

  • ... Should ... keywords (Element Should Contain, Page Should Contain, Title Should Be) check once, right now.
  • Wait Until ... keywords (Wait Until Page Contains, Wait Until Element Contains, Wait Until Element Is Visible) check repeatedly until the condition holds or the timeout runs out.

After Click Button submits the form, the browser loads a new page. A check that runs once may run before the new page is there. While building the login tests for chapter 6, a version written with Element Should Contain id:flash ... had three of its five tests fail in a single run with:

Element with locator 'id:flash' not found.

Changing it to Wait Until Element Contains made all five pass in every run after that, locally and on the grid. The rule: after anything that changes the page (a click that navigates, a form submit, an Ajax call), use a Wait Until keyword for the first check. Never fix it with Sleep: a fixed sleep is slow when the page is fast and still fails when the page is slower than your guess.

The default timeout of the Wait Until keywords is 5 seconds. Raise it for the whole suite where you import the library:

Library           SeleniumLibrary    timeout=10s

or per call with timeout=20s on a single keyword. The flaky tests course covers timing problems in general.

Running headless#

On a CI agent there is no screen, so you run headless. SeleniumLibrary accepts headlesschrome and headlessfirefox as browser names. When we switched the suite from the next chapter to headlesschrome and changed nothing else, the submit test failed:

Submitting The Form Shows A Confirmation                              | FAIL |
ElementClickInterceptedException: Message: element click intercepted: Element is not clickable at point (158, 857)

A headless browser starts with a small default window, much smaller than your screen, so the submit button sat outside the visible area under another element. Set a window size right after opening the browser:

    Open Browser    ${url}    headlesschrome
    Set Window Size    1920    1080

With that, the test passed headless in Chrome and Firefox. When a test passes on your screen and fails headless or in CI, the window size is the first thing to check.

After clicking "Log in", a test checks Element Should Contain id:flash Welcome and fails now and then with "element not found". Which change fixes it properly?

Element Should Contain checks once, so the library timeout does not apply to it. The Wait Until variant retries until the text appears and returns as soon as it does; a sleep only guesses.

Screenshots on failure#

You do not need to write anything for this: when a SeleniumLibrary keyword fails, the library calls Capture Page Screenshot and embeds the image in log.html next to the failing step. That one screenshot usually tells you more than the error message. The behaviour is the library's run_on_failure setting, which you can change on import if you ever need something else.

The test works, but it mixes what is being tested with how the page is built: locators, URLs and browser names are all inline. The next chapter fixes that.