Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Keyword based test automation for the web.

License Python versions Release Windows Acceptance Linux Acceptance MacOS Acceptance Tested with Slack

Table of Contents


QWeb is a powerful and versatile Robot Framework library that enables efficient and reliable web testing and automation. One of the key strengths of QWeb is its intuitive and user-friendly syntax, which makes it easy to write and maintain complex test cases.

QWeb aims to make web automation easy and maintainable by:

  • providing an intuitive and user-friendly syntax for writing and maintaining complex test cases.
  • providing smart locators: finding elements by text or by any attribute value with a simple syntax
  • automatically handling latencies etc. via automatic wait times
  • automatically handling frames
  • automatically handling unexpected alerts
  • providing support for finding shadow dom elements with an easy syntax
  • providing in-built bitmap comparison for special cases where element can't be identified by any other means
  • being technology agnostic and providing extensive support for various web technologies/frameworks

See examples.

Back To The Top


Python 3.8-3.11 and Robot Framework 4.1.3 or above.

(Note that support on Macs with Apple based silicon (M1) requires MacOS version 12/Monterey or above or custom installation.)



    pip install QWeb


    python3 -m pip install -U pip
    python3 -m pip install QWeb

Running the above command installs also supported Selenium and Robot Framework versions + other dependencies.

Automatic browser & driver management

Since Selenium 4.10.0 browser drivers can be automatically downloaded and installed using Selenium Manager, provided that driver is not found in PATH.

For Chrome browser_version can also be given; if your locally installed Chrome matches this version, it will be used. If not, a suitable version of Chrome for Testing will be automatically downloaded.

Examples in OpenBrowser keyword documentation

Manual driver management

For manual installation of drivers, please refer to Selenium documentation for more information OR use 3rd party packages like WebDriverManager.

Back To The Top


Keyword documentation

See list of keywords and their usage on

Back To The Top


Basic usage

The preferred way to interact with web elements is using their text property. Most elements like input fields and dropdowns can also be found by closest label (text).

*** Settings ***
Library    QWeb     # Import library

*** Test Cases ***
Basic interaction
    OpenBrowser      chrome   # Open chrome and goto given url
    VerifyText          The animal friendly clothing company            # Assert heading text
    ClickText           Scar the Lion                                   # Click link text
    ClickText           Add to cart                                     # Click *button* with specific text
    DropDown            Size            Large                           # Select value (Large) from dropdown (Size)

Shadow DOMs and visibility

Most common cases when text or element is not found are:

  • Element has (incorrectly?) some attribute set so, that it's considered invisible.
  • Element is under shadow dom (i.e. has #shadow-root parent element)

QWeb searches for visible elements by default, but can be instructed to work with invisible elements as well. See keyword documentation of SetConfig and the following parameters:

  • Visibility
  • Offsetcheck
  • InViewport

Elements under shadow DOM can not be found using xpaths. However, all *Text, *Item and *Input keywords do support extending the search to Shadow DOM elements. We intentionally keep this under separate setting for ensuring compatibility with older test cases.


*** Settings ***
Library    QWeb     # Import library

*** Test Cases ***
Click shadow dom element
  SetConfig            ShadowDOM            True  # extends search to shadow dom elements
  OpenBrowser          chrome://settings/content/popups   chrome
  ClickText            Sites can send pop-ups 

Timeouts and anchors

By default QWeb tries to locate the element 10 seconds (default time can be configured). Timeout can also be individually given for each keyword as an argument.

When text to be found is not unique, an 'anchor' argument can be given to pinpoint which instance of text we want to interact with. Anchor can be either another text nearby or index.

ClickText   Sign-in
ClickText   Sign-in     timeout=30

ClickText   Sign-in     anchor=Email
ClickText   Sign-in     index=3

Other locators

Non-textual locators can be used with ClickElementand ClickItemkeywords.

ClickElement    xpath\=//button[@class="my_class"]   # xpath
ClickItem       Increment quantity                   # alt text

Working with tables

QWeb includes keywords to interact with table data easily.

Consider the following table as an example: Example table

UseTable    Firstname

${row}=     GetTableRow     //last                        # returns 5
${row}=     GetTableRow     //last    skip_header=True    # returns 4
${row}=     GetTableRow     Jim                           # returns 4
${row}=     GetTableRow     Jim    skip_header=True       # returns 3

${cell_value}=     GetCellText     r1c2                   # Returns "John", first name is column 2.

${cell_value}=     GetCellText     r-1/c2                 # Returns "Tina", -1 points to last row
${cell_value}=     GetCellText     r-2/c2                 # Returns "Jim", -2 points to second last row

Changing configuration

QWeb's behavior can be changed with SetConfig keyword.

SetConfig     SearchMode     Draw       # Highlight all found elements with blue rectangle

SetConfig     DefaultTimeout    60s     # change default/automatic timeout for all keywords
VerifyText    User account created      # Re-tries to find text "User account created" 60 seconds and then fails, if text is not visible

Running with Python

QWeb can be used directly with Python as well.

from QWeb import QWeb

qweb = QWeb()

qweb.open_browser("about:blank", "chrome")
title = qweb.get_title()
# returns 'W3Schools Tryit Editor'
qweb.verify_text("The select element")
qweb.drop_down("Choose a car", "Saab")
qweb.verify_text("Your input was received as:")

More examples on QWeb tutorial.

Back To The Top



Back To The Top


Found an bug? Want to propose a new feature or improve documentation? Please start by checking our contribution guide

Back To The Top


Want to join the community at Slack? On the official Robot Framework workspace, there is a QWeb channel where you can discuss with others about keywords, issues and improvements. Join Now

Back To The Top


Apache 2.0 License. See LICENSE.

Back To The Top