Keyword based test automation for the web.
QWeb is an open source web automation interface in Robot Framework. It makes automation rapid, robust, and fun.
QWeb aims to make web automation easy and maintainable by:
- providing high level keywords for accessing any web page element
- preferring text locators (UI texts) but supporting also other locator strategies (xpaths, css selectors)
- automatically handling latencies etc. via automatic wait times
- automatically handling unexpected alerts
- minimizing the maintenance effort
See examples.
Python 3.7-3.10 and Robot Framework 3.2.2 or above. Browser drivers need to be installed separately.
(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 QWebRunning the above command installs also supported Selenium and Robot Framework versions + other dependencies, but you still need to install browser drivers separately. Please refer to Selenium documentation for more information on how to install browser drivers manually OR use 3rd party packages like WebDriverManager.
See list of keywords and their usage on
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 https://qentinelqi.github.io/shop 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)
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.
Example:
*** Settings ***
Library QWeb # Import library
SetConfig ShadowDOM True # extends search to shadow dom elements
OpenBrowser chrome://settings/content/popups chrome
ClickText Sites can send pop-ups 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=3Non-textual locators can be used with ClickElementand ClickItemkeywords.
ClickElement xpath\=//button[@class="my_class"] # xpath
ClickItem Increment quantity # alt text
QWeb includes keywords to interact with table data easily.
Consider the following table as an example:
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 rowQWeb'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 visibleMore examples on QWeb tutorial.
See RELEASE.md
Found an bug? Want to propose a new feature or improve documentation? Please start by checking our contribution guide
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
Apache 2.0 License. See LICENSE.