robotframework-RobotOil 1.0.0

Quality of life upgrades for common-use Keywords in the Robot Framework and SeleniumLibrary packages.

RobotOil

• RobotOil
  • Introduction
  • Dependencies
  • Installation
  • Importing RobotOil
    • Importing into Robot
    • Importing into Python
  • Features and Examples
    • Smart Browser
      • Smart Browser Example
    • Smart Keywords
      • Smart Click Example
      • Smart Keywords from Python
  • Conclusion

Introduction

RobotOil is a library of quality-of-life features for automated test case development with Robot Framework and SeleniumLibrary.

Enhancements include the option of persistent browser sessions to assist with debugging your scripts and "Smart" versions of common-use SeleniumLibrary Keywords to make navigating your web application even easier. Additionally, everything within RobotOil may be executed from either a Robot Test Suite OR the execution of a Python file.

Grease the gears of your next automation project with RobotOil!

Dependencies

Requires RobotFramework and SeleniumLibrary. Use these commands to stay up to date with the latest versions.

pip install robotframework -U
pip install robotframework-seleniumlibrary -U

Installation

Recommend using pip to install RobotOil.

pip install robotframework-RobotOil -U

If using GitHub, copy the RobotOil folder from the src folder to anywhere in your PATH. Ideally, to the (your Python library)/Lib/site-packages folder.

Importing RobotOil

RobotOil and all Keywords within may be executed from either a Robot Test Suite or a Python module.

Importing into Robot

Simply call RobotOil as Library within your Test Suite or Resource file of choice.

*** Settings ***
Library    RobotOil

Importing into Python

Import the RobotOil module and class into a Python file. All RobotOil Keywords/methods may be called from this class.

from RobotOil import RobotOil

oil_can = RobotOil()

Features and Examples

Smart Browser

If you've worked with Selenium, you've likely noticed how every automated test needs to begin with the creation of a new browser session. Even with debugging tools native to many IDE's, automated test cases with traditional browser sessions can become incredibly time-consuming to maintain when needing to, say, correct step 48 of a 50 step test case but needing to execute steps 1-47 everytime you try a new fix.

By contast, Smart Browser sessions provide the option to remain open after a Robot or Python test execution has finished allowing them to be reusable for additonal sessions as long as the browser remains open and no new sessions are created.

Smart Browser Example

Create a file named oil_test.robot anywhere on your machine and enter the following code:

*** Settings ***
Library           SeleniumLibrary
Library           RobotOil

*** Test Cases ***
Begin Session
    Open Smart Browser    https://phptravels.com/demo    chrome    persist

In a console, run the command robot -t "Begin Session" PATH_TO_TEST_SUITE\oil_test.robot. A chrome browser session is started and the test site is navigated to. Leave this browser open before beginning the next step.

In the same oil_test.robot Test Suite, add this Test Case:

Continue Session
    Use Current Smart Browser
    Maximize Browser Window

Run this Test Case via robot -t "Continue Session" PATH_TO_TEST_SUITE\oil_test.robot. If all goes well, you should see the same browser session you opened earlier become maximized.

You may continue to send commands to Smart Browser Sessions via Use Current Smart Browser until either closing the browser or creating a new Smart Browser.

When it's actually time to close up the browser and any webdrivers that may be hanging around, simply call the Cleanup Smart Browser Keyword.

Smart Keywords

The SeleniumLibrary package features a wide variety of powerful Keywords for interacting with web elements. Keywords like Click Element, Input Text, and so forth probably make up the bulk of most web automation projects using Robot Framework.

However, these Keywords are often limited when dealing with the unpredictability of page load times and elements appearing asynchronously on a given web page. These limitations cause unexpected failures and sometimes require complex or time-consuming workarounds.

Smart Keywords offer enhanced versions of these SeleniumLibrary Keywords that account for this unpredictability and provide additonal quality-of-life improvements by:

1. Automatically waiting for targeted elements to be visible before attempting to interact
2. Allowing for the "time to wait" to be established per Keyword call
3. Being accessible from a Python method as well as a Robot Test Case

Smart Click Example

In the same oil_test.robot Test Suite from earlier, copy the following code:

Text Retrieval Test
    Open Smart Browser    https://the-internet.herokuapp.com/dynamic_loading/2    chrome
    Maximize Browser Window
    Click Element   css:#start > button
    ${hello_text}    Get Text    css:#finish

Run using robot -t "Text Retrieval Test" PATH_TO_TEST_SUITE\oil_test.robot.

This test ends up failing because the Get Text keyword gives up looking for the #finish id before this element can become available.

A typical workaround to this issue might include having to write in a Wait For Page to Contain Element or worse, a call to the dreaded Sleep Keyword. Static waits like Sleep and the variability of internet connections and server responses do NOT mix well and having to write out a Wait For... Keyword before nearly every test step is a chore.

Instead, simple add the word Smart to the Get Text keyword so the last line looks like this:

${hello_text}    Smart Get Text    css:#finish

And run the test again. The test passes due to Smart Get Text understanding that it has to wait until the "finish" element is visible before attempting to retrieve its text.

If you want to ensure that the finish element, or any element you want to interact with using a Smart Keyword, becomes visible within a known time limit, you may simply give the timeout parameter a specific argument like so:

${hello_text}    Smart Get Text    css:#finish    timeout=120

This will make Smart Get Text wait for up to 2 minutes for the finish element to become visible before attempting to click the button.

Note: Not all SeleniumLibrary Keywords are available by simply adding Smart as a prefix. If a keyword has not been explicitly added to the Smart Keywords class, you may add Smart Keyword to a SeleniumLibrary keyword and receive the same benefits. For example:

${hello_text}    Smart Keyword    Get Text    css:#finish    timeout=120

With this enhancement, you'll never have to explicitly call another Sleep or Wait For... Keyword in your test cases again!

Smart Keywords from Python

One of RobotFramework's greatest advantages is the ease of creating custom Python libraries and methods and being able to execute these directly from a Robot Test Case. This is especially useful when needing to write out a more complex set of actions from Python where features like nested for loops, while loops, etc, are available. To further facilitate this capability, Smart Keywords are also accessible from your extended Python libraries and methods.

Create a file named click_test.py anywhere on your machine, copy the following example code, and execute the file:

from RobotOil import RobotOil

oil_can = RobotOil()

oil_can.open_smart_browser('https://phptravels.com/', 'chrome', 'persist')
oil_can.browser.maximize_window()
oil_can.smart_click_element('link:Features')
oil_can.smart_click_element('link:Main Features')
oil_can.smart_click_element('link:Demo')

To move this functionality back into your established Robot Test Cases, simply wrap this code in a method:

from RobotOil import RobotOil

oil_can = RobotOil()

def python_clicking():
    oil_can.open_smart_browser('https://phptravels.com/', 'chrome', 'persist')
    oil_can.browser.maximize_window()
    oil_can.smart_click_element('link:Features')
    oil_can.smart_click_element('link:Main Features')
    oil_can.smart_click_element('link:Demo')

And import the file into your oil_test.robot Test Suite:

*** Settings ***
Library           SeleniumLibrary
Library           RobotOil
Library           PATH_TO_CLICK_TEXT/click_test.py

From there, simply call Python Clicking from a Test Case of your choice:

*** Test Cases ***
Python Example
    Python Clicking

You may now leverage the already powerful SeleniumLibrary Keywords, with Smart Keyword enhancements, DIRECTLY from Python, and back into your Robot Test Cases!

Conclusion

I hope you enjoy the additional capabilities and ease-of-use that RobotOil brings to automated web testing with RobotFramework.

Please don't hesitate to reach out with questions or suggestions on GitHub