Toolium Documentation · Toolium is a Python wrapper tool of Selenium and Appium libraries to test web and mobile applications in a single project. It provides a way of choosing and

Toolium DocumentationRelease 1.7.1-688

Rubén González Alonso, Telefónica I+D

May 18, 2020

Contents

1 Getting Started 3

2 Contributing 5

3 Main Features 7

4 Library Reference 94.1 Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2 Page Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.3 BDD Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.4 Visual Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.5 Tests Result Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284.6 Toolium Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.7 toolium packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414.8 toolium modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

5 Indices and Tables 67

Python Module Index 69

Index 71

i

ii

Toolium Documentation, Release 1.7.1-688

Toolium is a Python wrapper tool of Selenium and Appium libraries to test web and mobile applications in a singleproject. It provides a way of choosing and configuring the driver through a configuration file, implements a PageObject pattern and includes a simple visual testing solution.

Contents 1

https://travis-ci.org/Telefonica/toolium

https://coveralls.io/github/Telefonica/toolium

https://www.codacy.com/app/rgonalo/toolium?utm_source=github.com&utm_medium=referral&utm_content=Telefonica/toolium&utm_campaign=Badge_Grade

http://toolium.readthedocs.org/en/latest


2 Contents

CHAPTER 1

Getting Started

The requirements to install Toolium are Python 2.7 or 3.3+ and pip. If you use Python 2.7.9+, you don’t need to installpip separately.

Run pip install toolium to install the latest version from PyPi. It’s highly recommendable to use a virtualenv.

The main dependencies are:

• Selenium: to test web applications in major browsers (Firefox, Chrome, Internet Explorer, Edge, Safari, Opera)

• Appium-Python-Client: to test mobile applications (native, hybrid or web) in Android or iOS devices/emulators.

• requests: to test APIs

Using toolium-template

The easiest way of getting started is to clone toolium-template project, run the example test and add your own testsand configuration.

$ git clone [email protected]:Telefonica/toolium-template.git$ cd toolium-template$ pip install -r requirements.txt

Now, just follow toolium-template instructions to know how to start your testing project.

Running toolium-examples

You can also clone toolium-examples to get more examples about how to use the library to test web, Android or iOSapplications, in different scenarios.

$ git clone [email protected]:Telefonica/toolium-examples.git$ cd toolium-examples$ pip install -r requirements.txt

Now, just follow toolium-examples instructions to run the examples of the tests.

3

http://www.python.org

https://pypi.org/project/pip

https://pypi.org/project/toolium

http://docs.seleniumhq.org/

https://github.com/appium/python-client

http://docs.python-requests.org

https://github.com/Telefonica/toolium-template

https://github.com/Telefonica/toolium-template#running-tests

https://github.com/Telefonica/toolium-examples

https://github.com/Telefonica/toolium-examples#running-tests


4 Chapter 1. Getting Started

CHAPTER 2

Contributing

If you want to collaborate in Toolium development, feel free of forking it and asking for a pull request.

Don’t forget to run unit tests:

$ git clone [email protected]:<your_github_user>/toolium.git$ cd toolium$ python setup.py test

Finally, before accepting your contribution, we need you to sign our Contributor License Agreement and send it [email protected].

5

https://github.com/Telefonica/toolium

https://raw.githubusercontent.com/telefonicaid/Licensing/master/ContributionPolicy.txt

mailto:[email protected]


6 Chapter 2. Contributing

CHAPTER 3

Main Features

• Choosing driver through a configuration file

• Page Object pattern

• BDD integration

• Visual testing solution

• Tests result analysis

7


8 Chapter 3. Main Features

CHAPTER 4

Library Reference

4.1 Driver Configuration

Toolium allows to run tests on web browsers (using Selenium) or on mobile devices (using Appium). To choose thebrowser or the mobile OS, configure type property in [Driver] section in conf/properties.cfg file withone of these values: firefox, chrome, iexplore, edge, safari, opera, phantomjs, ios or android.

The following example shows how to choose Firefox:

[Driver]type: firefox

If driver is not needed, typically in API tests, disable it using an empty string, api or no_driver:

[Driver]type: api

By default, Toolium configuration is loaded from conf/properties.cfg and conf/local-properties.cfg files. If different properties files are used for different environments, they can be selected using a sys-tem property named Config_environment. For example, if Config_environment value is android,Toolium configuration will be loaded from conf/properties.cfg, conf/android-properties.cfg andlocal-android-properties.cfg files:

Nose:

$ Config_environment=android nosetests web/tests/test_web.py

Pytest:

$ Config_environment=android pytest web_pytest/tests/test_web_pytest.py

Behave:

$ behave -D Config_environment=android

9


• Browser Configuration

• Mobile Configuration

• Remote Driver Configuration

• Multiple Simultaneous Drivers

• Reuse Driver

4.1.1 Browser Configuration

Common Configuration

To choose the browser in which Selenium will execute the tests, configure type property in [Driver] section in proper-ties.cfg file with one of these values: firefox, chrome, iexplore, edge, safari, opera or phantomjs.

The following example shows how to choose Firefox:


By default, the browser is maximized. To define a different window size, configure window_width and window_heightproperties in [Driver] section:

[Driver]window_width: 1024window_height: 768

Mandatory Configuration

Besides selecting the browser, some specific configuration is needed when running locally.

Firefox (with Selenium 3)

• Download geckodriver-*.zip

• Unzip file and save the executable in a local folder

• Configure driver path in [Driver] section in properties.cfg file

[Driver]type: firefoxgecko_driver_path: C:\Drivers\geckodriver.exe

Firefox 48+ (with Selenium 2)

• Download geckodriver-*.zip



10 Chapter 4. Library Reference

https://github.com/mozilla/geckodriver/releases

https://github.com/mozilla/geckodriver/releases


[Driver]type: firefoxgecko_driver_path: C:\Drivers\geckodriver.exe

• Enable Gecko/Marionette driver in [Capabilities] section in properties.cfg file

[Capabilities]marionette: true

Firefox 47 (with Selenium 2)

• No extra configuration is needed


Chrome

• Download chromedriver_*.zip



[Driver]type: chromechrome_driver_path: C:\Drivers\chromedriver.exe

Internet Explorer

• Download IEDriverServer_Win32_*.zip

• It’s recommended to use Win32 version, because x64 version is very slow



[Driver]type: iexploreexplorer_driver_path: C:\Drivers\IEDriverServer.exe

Edge

• Download MicrosoftWebDriver.msi

• Install MicrosoftWebDriver.msi


[Driver]type: edgeedge_driver_path: C:\Drivers\MicrosoftWebDriver.exe

4.1. Driver Configuration 11

http://chromedriver.storage.googleapis.com/index.html

http://selenium-release.storage.googleapis.com/index.html

https://www.microsoft.com/en-us/download/details.aspx?id=48212


Safari

• Download SafariDriver.safariextz

• Open file in Safari and install it

[Driver]type: safari

Opera

• Download operadriver_*.zip



[Driver]type: operaopera_driver_path: C:\Drivers\operadriver.exe

PhantomJS

• Download phantomjs-*.zip



[Driver]type: phantomjsphantomjs_driver_path: C:\Drivers\phantomjs.exe

Additional Configuration

Firefox

To use a custom Firefox profile, create a [FirefoxPreferences] configuration section and add every preference that youwant to configure with its value.

For example, the following configuration allows to download files without asking user:


[FirefoxPreferences]browser.download.folderList: 2browser.download.dir: C:\tmpbrowser.helperApps.neverAsk.saveToDisk: application/octet-streamdom.serviceWorkers.enabled: True

Firefox plugins can also be installed adding their file paths to [FirefoxExtensions] configuration section.

For example, the following configuration exports network information to har files:


http://selenium-release.storage.googleapis.com/index.html

https://github.com/operasoftware/operachromiumdriver/releases

http://phantomjs.org/download.html



[FirefoxPreferences]devtools.netmonitor.har.enableAutoExportToFile: Truedevtools.netmonitor.har.defaultLogDir: /tmp/hardevtools.netmonitor.har.forceExport: Falsedevtools.netmonitor.har.pageLoadedTimeout: 10extensions.netmonitor.har.enableAutomation: Trueextensions.netmonitor.har.autoConnect: Truedevtools.netmonitor.har.defaultFileName: network-test

[FirefoxExtensions]firebug: resources/firebug-3.0.0-beta.3.xpi

To use a predefined firefox profile, configure the profile directory in [Firefox] configuration section:


[Firefox]profile: resources/firefox-profile.default

When firefox is installed in a non-default location, configure the firefox binary path in [Firefox] configuration section:


[Firefox]binary: /usr/local/firefox_beta/firefox

To configure Firefox arguments, create a [FirefoxArguments] configuration section and add every argument that youwant to configure with its value.

For example, to open firefox in a private browsing mode:


[FirefoxArguments]-private:

Chrome

To configure Chrome preferences, create a [ChromePreferences] configuration section and add every preference thatyou want to configure with its value.

For example, the following configuration allows to download files without asking user:

[Driver]type: chrome

[ChromePreferences]download.default_directory: C:\tmp

To configure Chrome arguments, create a [ChromeArguments] configuration section and add every argument that youwant to configure with its value.


https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#Browser

https://cs.chromium.org/chromium/src/chrome/common/pref_names.cc

https://cs.chromium.org/chromium/src/chrome/common/chrome_switches.cc


For example, to use a predefined chrome profile:


[ChromeArguments]user-data-dir: C:\Users\USERNAME\AppData\Local\Google\Chrome\User Data

When Chrome is installed in a non-default location, configure the Chrome binary path in [Chrome] configurationsection:


[Chrome]binary: /usr/local/chrome_beta/chrome

Another examples showing how to use Chrome Device Mode in two different ways:


[ChromeMobileEmulation]deviceName: Google Nexus 5


[ChromeMobileEmulation]deviceMetrics: { "width": 360, "height": 640, "pixelRatio": 3.0 }userAgent: Mozilla/5.0 (Linux; Android 4.2.1; en-us; Nexus 5 Build/JOP40D)→˓AppleWebKit/535.19 (KHTML, like Gecko)

Chrome/18.0.1025.166 Mobile Safari/535.19

4.1.2 Mobile Configuration

To choose mobile operating system in which Appium will execute the tests, configure type property in [Driver] sectionin properties.cfg file with one of these values: ios or android.

The following example shows how to choose Android:

[Driver]type: android

Moreover, configure Appium properties in [AppiumCapabilities] section in properties.cfg file. The following exampleshows how to configure Appium to run tests over TestApp app on an iPhone 6 with iOS 8.3:

[Driver]type: ios

[AppiumCapabilities]automationName: AppiumplatformName: iOSdeviceName: iPhone 6platformVersion: 8.3app: http://server_url/TestApp.zip


https://sites.google.com/a/chromium.org/chromedriver/mobile-emulation


See http://appium.io/slate/en/master#appium-server-capabilities for the complete Appium capabilities list.

4.1.3 Remote Configuration

Basic Configuration

This section shows how to launch tests on a remote Selenium, Appium or GGR server. Configure its properties in[Server] section in properties.cfg file:

[Server]enabled: truessl: falsehost: SERVER_IPport: SERVER_PORTusername: SERVER_USERNAMEpassword: SERVER_PASSWORDvideo_enabled: falselogs_enabled: false

enabled

true: remote execution is enabled, tests will be executed remotelyfalse: remote execution is disabled, tests will be executed locally

ssl

true: use https in server urlfalse: use http in server url

host

Server ip or host name where Selenium Server, Appium Server or Selenium Grid is already started

port

Port number where server is listening

username

Username that is passed to Selenium Grid hub when it requires basic authentication, like in GGR

password

Password that is passed to Selenium Grid hub when it requires basic authentication, like in GGR


http://appium.io/slate/en/master#appium-server-capabilities


video_enabled

This property is only valid using Selenium Grid Extras orGGR with Selenoid as remote server, that allow recording videos of testexecutions.

true: remote video recording is enabled, a video of the test execution will be recorded and saved locallyfalse: remote video recording is disabled

logs_enabled

true: webdriver and GGR logs are downloaded and saved to local files after test executionfalse: webdriver and GGR logs are downloaded and saved to local files only if the test fails

Remote Driver Capabilities

To configure remote driver, create a [Capabilities] section in properties.cfg file and add every capability that you wantto configure with its value.

The following example requests to the Selenium Grid Hub a Windows environment with Internet Explorer 11:

[Driver]type: iexplore

[Capabilities]version: 11platform: WINDOWS

See https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities for the complete Selenium capabilities list.

4.1.4 Multiple Simultaneous Drivers

By default, Toolium creates a driver using the configuration in properties.cfg and all page objects and elements usethis driver to execute their commands. The driver is accessible from tests in self.driver.

Although it is also possible to create additional drivers with DriverWrapper class.

For instance, to create a driver with the same configuration as the default driver (in this case two Firefox drivers):


second_wrapper = DriverWrapper()second_wrapper.connect()

To create a driver with a different configuration (in this case one Android driver and one Firefox driver):

[Driver]type: android


https://github.com/groupon/Selenium-Grid-Extras

https://github.com/aerokube/ggr

https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities


second_wrapper = DriverWrapper()second_wrapper.config.set('Driver', 'type', 'firefox')second_wrapper.connect()

The driver wrapper contains the driver instance, that can be used as a regular driver, e.g.:

second_wrapper.driver.find_element_by_xpath('//form')

To use the second driver in page objects and their elements, pass the driver wrapper to the page object constructor:

login_page = LoginPageObject(second_wrapper)

and, instead of define page elements as page object attributes, create them inside init_page_elements method:

class LoginPageObject(PageObject):def init_page_elements(self):

self.username = InputText(By.ID, 'username')self.password = InputText(By.ID, 'password')

4.1.5 Reuse driver

By default, in Toolium, the driver is initialized and closed before and after each test. This isolates tests avoidingproblems by sharing resources, but also means that tests are slower. Reusing the driver will speed up your testsexecution, but it needs a careful handling of the initial status of each test.

There are several properties that show how to reuse the driver. They are under [Driver] section in conf/properties.cfg:

[Driver]reuse_driver: truereuse_driver_session: falserestart_driver_after_failure: true

• reuse_driver: if enabled, driver will be reused within the scope of a class in unittest, a module in pytestand a feature in behave or lettuce.

• reuse_driver_session: if enabled, driver will be reused for all the tests in the execution. When usingbehave or pytest, the driver will be closed after all tests, but if you are using unittest, the driver will remain openafter tests.

• restart_driver_after_failure: if enabled, driver will always be restarted after a failure in a test.

Behave tags

Independently of the properties configuration, Toolium defines two behave tags to configure driver:

• @reuse_driver: feature tag to indicate that all scenarios in this feature should share the driver. The browserwill not be closed between tests.

• @reset_driver: identifies a scenario that should not reuse the driver. The browser will be closed and reopenbefore this test.



4.2 Page Objects

Toolium implements Page Object pattern, where a page object represents a web page or a mobile screen (or a part ofthem) and a page element is any of the elements contained in those pages (inputs, buttons, texts, . . . ).

Toolium loads page elements in lazy loading, so they are searched in Selenium or Appium when they are used, notwhen they are defined.

4.2.1 Basic usage

To define a page object in Toolium, first create a class derived from PageObject and add a class attribute for eachpage element. Take into account that each page element has two mandatory initialization arguments: locator type andlocator value. Besides, page object class must implement a method for each action allowed in this page.

Example of a page object definition:

from toolium.pageobjects.page_object import PageObjectfrom toolium.pageelements import InputText, Button

class LoginPageObject(PageObject):username = InputText(By.ID, 'username')password = InputText(By.ID, 'password')login_button = Button(By.XPATH, "//form[@id='login']/button")

def login(self, username, password):self.username.text = usernameself.password.text = passwordself.login_button.click()

Example of a test using the previous page object:

def test_login(self):LoginPageObject().login('user', 'pass')...

4.2.2 Page element types

There are different page elements classes that represent different element types of a page: Text, Button, InputText,Checkbox, InputRadio, Link, Select and Group.

For any other existing element type, PageElement class can be used.

Methods

Each element type has specific methods to get text, set text (InputText), select an option (Select) or click the element(Button), for example.

username = InputText(By.ID, 'username')

# Get text valueinput_value = username.text

# Set text valueusername.text = 'username'



Page elements only implement the most commonly used methods. When performing any other action with the element,get the web element of the page element and execute the action. web_element property returns the Selenium or AppiumWebElement.

username = InputText(By.ID, 'username')

# Check if the element is enabledenabled = username.web_element.is_enabled()

Parent

Page elements have an optional argument parent, that points to the container of the element. The page element will besearched within the parent element, instead of the entire page. The parent can be a PageElement, a WebElement or alocator tuple.

form = PageElement(By.XPATH, "//form[@id='login']")login_button = Button(By.XPATH, "./button", parent=form)

Shadowroot

Page elements have an optional argument shadowroot, with the CSS selector of the shadowroot parent. The pageelement will be searched within the shadowroot parent element, instead of the entire page.

It is only supported for PageElement objects identified by CSS, so it is not supported for PageElements, Group,elements with nested encapsulation or PageElement identified by other selector types.

login_button = Button(By.CSS_SELECTOR, "css_selector", shadowroot="shadowroot_css_→˓selector")

Group

Group is a page element that contains other child page elements, that will be searched within the group element,instead of the entire page.

from toolium.pageobjects.page_object import PageObjectfrom toolium.pageelements import InputText, Button, Group

class Form(Group):username = InputText(By.ID, 'username')password = InputText(By.ID, 'password')login_button = Button(By.XPATH, "./button")

class LoginPageObject(PageObject):form = Form(By.XPATH, "//form[@id='login']")

def login(self, username, password):self.form.username.text = usernameself.form.password.text = passwordself.form.login_button.click()

4.2. Page Objects 19


4.2.3 Find multiple page elements

Toolium provides some new classes that represent lists of page elements: PageElements, Texts, Buttons, InputTexts,Checkboxes, InputRadios, Links, Selects and Groups.

These lists help execute an action on all their elements, for example to clear all inputs of a web page:

inputs = InputTexts(By.XPATH, '//input')

for input in inputs.page_elements:input.clear()

4.2.4 Concurrency issues

If using multiple instances of a page object class at the same time (e.g. having two simultaneous drivers), classattributes can not be used to define page elements. In this case, page elements must be defined as instance attributesthrough a method called init_page_elements.

from toolium.pageobjects.page_object import PageObjectfrom toolium.pageelements import InputText, Button

class LoginPageObject(PageObject):def init_page_elements(self):

self.username = InputText(By.ID, 'username')self.password = InputText(By.ID, 'password')self.login_button = Button(By.XPATH, "//form[@id='login']/button")

def login(self, username, password):self.username.text = usernameself.password.text = passwordself.login_button.click()

4.2.5 Mobile page object

MobilePageObject class allows using the same test case in Android and iOS, because an Android or iOS page objectis instantiated depending on driver configuration. It’s useful when testing the same mobile application in Android andiOS.

Three page objects must be defined: a base page object with the commons methods, derived from MobilePageObject,and an Android and iOS page objects with their specific locators and methods, derived from base page object.

For example, a base page object for login functionality:

from toolium.pageobjects.mobile_page_object import MobilePageObject

class BaseLoginPageObject(MobilePageObject):def login(self, username, password):

self.username.text = usernameself.password.text = passwordself.login_button.click()

The corresponding Android page object, where page elements are defined with their specific Android locators:



from selenium.webdriver.common.by import Byfrom toolium.pageelements import InputText, Buttonfrom toolium_examples.pageobjects.base.login import BaseLoginPageObject

class AndroidLoginPageObject(BaseLoginPageObject):username = InputText(By.ID, 'io.appium.android.apis:id/username')password = InputText(By.ID, 'io.appium.android.apis:id/password')login_button = Button(By.ID, "io.appium.android.apis:id/login_button")

And the iOS page object, where page elements are defined with their specific iOS locators:

from appium.webdriver.common.mobileby import MobileByfrom toolium.pageelements import InputText, Buttonfrom toolium_examples.pageobjects.base.login import BaseLoginPageObject

class IosLoginPageObject(BaseLoginPageObject):username = InputText(MobileBy.IOS_UIAUTOMATION, '.textFields()[0]')password = InputText(MobileBy.IOS_UIAUTOMATION, '.secureTextFields()[0]')login_button = Button(MobileBy.IOS_UIAUTOMATION, '.buttons()[0]')

Base, Android and iOS page objects must be defined in different files following this structure:

FOLDER/base/MODULE_NAME.pyclass BasePAGE_OBJECT_NAME(MobilePageObject)

FOLDER/android/MODULE_NAME.pyclass AndroidPAGE_OBJECT_NAME(BasePAGE_OBJECT_NAME)

FOLDER/ios/MODULE_NAME.pyclass IosPAGE_OBJECT_NAME(BasePAGE_OBJECT_NAME)

This structure for the previous login example should look like:

toolium_examples/pageobjects/base/login.pyclass BaseLoginPageObject(MobilePageObject)

toolium_examples/pageobjects/android/login.pyclass AndroidLoginPageObject(BaseLoginPageObject)

toolium_examples/pageobjects/ios/login.pyclass IosLoginPageObject(BaseLoginPageObject)

If page objects are simple enough, the three page objects could be defined in the same file, so the previous folderstructure is not needed.

Finally, test cases must use base page object instead of Android or iOS. During test execution, depending on the drivertype value, the corresponding Android or iOS page object will be instantiated.

from toolium_examples.pageobjects.base.login import BaseLoginPageObject

class Login(AppiumTestCase):def test_login(self):

BaseLoginPageObject().login(username, password)

4.2. Page Objects 21


4.3 BDD Integration

Toolium can be also used with behave and lettuce tests.

4.3.1 Behave

Behave tests should be developed as usual, only environment.py file should be modified to initialize driver and the restof Toolium configuration.

Environment methods should call to the corresponding Toolium environment methods, as can be seen in the followingexample:

from toolium.behave.environment import (before_all as toolium_before_all, before_→˓feature as toolium_before_feature,

before_scenario as toolium_before_scenario,after_scenario as toolium_after_scenario,after_feature as toolium_after_feature, after_

→˓all as toolium_after_all)

def before_all(context):toolium_before_all(context)

def before_feature(context, feature):toolium_before_feature(context, feature)

def before_scenario(context, scenario):toolium_before_scenario(context, scenario)

def after_scenario(context, scenario):toolium_after_scenario(context, scenario)

def after_feature(context, feature):toolium_after_feature(context, feature)

def after_all(context):toolium_after_all(context)

After initialization, the following attributes will be available in behave context:

• context.toolium_config: dictionary with Toolium configuration, readed from properties.cfg

• context.driver_wrapper: DriverWrapper instance

• context.driver: Selenium or Appium driver instance

• context.utils: Utils instance

Behave userdata properties

Toolium properties can be modified from behave userdata configuration. For example, to select the driver type fromcommand line instead of using the driver type defined in properties.cfg:



$ behave -D Driver_type=chrome

Behave tags

Toolium defines two tags to configure driver:

• @reuse_driver: feature tag to indicate that all scenarios in this feature should share the driver. The browserwill not be closed between tests.

• @reset_driver: identifies a scenario that should not reuse the driver. The browser will be closed and reopenbefore this test.

• @no_driver: identifies a scenario or feature that should not start the driver, typically in API tests.

And other scenario tags to configure Appium tests:

• @no_reset_app: mobile app will not be reset before test (i.e. no-reset Appium capability is set to true)

• @reset_app: mobile app will be reset before test (i.e. no-reset and full-reset Appium capabilities are set tofalse)

• @full_reset_app: mobile app will be full reset before test (i.e. full-reset Appium capability is set to true)

• @android_only: identifies a scenario that should only be executed in Android

• @ios_only: identifies a scenario that should only be executed in iOS

Behave - Dynamic Environment

Optionally, some actions (labels) are defined in the Feature description as:

• Actions Before the Feature:

• Actions Before each scenario:

• Actions After each scenario:

• Actions After the Feature:

With a steps list executed in each moment identified with the label as the environment.py file. These steps are definedsimilar to others one.

Each step block is separated by a blank line.

Behave keywords are supported (Given, When, Then, And, But, Check, Setup).

Note: When using Drivers, Actions Before the Feature and Actions After the Feature directives (in the “dynamicenvironment” of a Feature) are only available if the execution for that Feature has been configured to reuse the driver.Otherwise, unexpected exceptions can be raised and execution may not finish successfully.

Example:

@reuse_driverFeature: Tests with the dynamic environmentAs a behave operator using multiples scenariosI want to append actions before the feature, before each scenario, after each

→˓scenario and after the feature.

(continues on next page)

4.3. BDD Integration 23


(continued from previous page)

Actions Before the Feature:Given wait 3 secondsAnd waitrty 3 secondsAnd wait 3 secondsAnd step with a table

| parameter | value || sub_fields_1 | sub_value 1 || sub_fields_2 | sub_value 2 |

Actions Before each Scenario:Given the user navigates to the "www.google.es" urlWhen the user logs in with username and passwordAnd wait 1 secondsAnd wait 1 seconds

Actions After each Scenario:And wait 2 secondsAnd wait 2 seconds

Actions After the Feature:And wait 4 secondsAnd step with another step executed dynamicallyAnd wait 4 seconds

All kind of steps are allowed:

• with tables

• executing another step internally

In case that a step of dynamic environment fails, an exception is printed on console, i.e. ‘waitrty 3 seconds’ step.When this happens, steps of the affected scenarios for that precondition are not executed (skipped) and, after that, firststep defined in those scenarios will be automatically failed because of that precondition exception, in order to properlyfail the execution and show the stats.

4.3.2 Lettuce

Lettuce tests should be developed as usual, only terrain.py file should be modified to initialize driver and the rest ofToolium configuration.

Terrain methods should call to the corresponding Toolium terrain methods, as can be seen in the following example:

from lettuce import after, beforefrom toolium.lettuce.terrain import (setup_driver as toolium_setup_driver, teardown_→˓driver as toolium_teardown_driver,

teardown_driver_all as toolium_teardown_driver_→˓all)

@before.each_scenariodef setup_driver(scenario):

toolium_setup_driver(scenario)

@after.each_scenariodef teardown_driver(scenario):

(continues on next page)



(continued from previous page)

toolium_teardown_driver(scenario)

@after.alldef teardown_driver_all(total):

toolium_teardown_driver_all(total)

After initialization, the following attributes will be available in world object:

• world.toolium_config: dictionary with Toolium configuration, readed from properties.cfg

• world.driver_wrapper: DriverWrapper instance

• world.driver: Selenium or Appium driver instance

• world.utils: Utils instance

4.4 Visual Testing

4.4.1 How does visual testing work?

Visual Testing in Toolium is a tool for checking automatically if your web pages or mobile apps are rendered asexpected. Tests are executed the same way, both on Selenium and Appium.

To achieve this goal, this tool follows these steps:

• It takes a screenshot of the current web page or mobile screen (a full screenshot or a single element).

• Then, if exists a previous capture with the same name, it compares both of them and shows their differences.

• If not, it saves the screenshot to be used as a base in later executions. Probably these images might be reviewedmanually to assure that can be used as expected result.

As web pages and mobile applications look different when using different browsers, mobile devices, resolutions, etc.Toolium provides you with a way of storing different base images, called baselines, through a configuration propertycalled baseline_name.

The libraries used to make the comparisons of the images are Needle, another python tool for visual testing withSelenium, and Pillow, the basic python library for image management.

After every execution, the tool generates a HTML report with the screenshots and the resulting comparisons. Thefollowing figure shows an example of this report. As can be seen, there’s a row per assert in your tests, with itsbackground in green or red, depending on the comparison.

4.4. Visual Testing 25

https://github.com/bfirsh/needle

https://github.com/python-pillow/Pillow


4.4.2 How to execute it?

Visual asserts could be used in different ways:

• Comparing a full page screenshot with the expected result: a previously captured image with the same screen-shot_name

self.assert_full_screenshot(screenshot_name)

• Comparing a single element, represented by a PageElement

form_page_element = PageElement(By.XPATH, '//form')self.assert_screenshot(form_page_element, screenshot_name)

or

form_page_element = PageElement(By.XPATH, '//form')form_page_element.assert_screenshot(screenshot_name)

• Comparing a single element, represented by a WebElement

form_element = self.driver.find_element_by_xpath('//form')self.assert_screenshot(form_element, screenshot_name)

• Comparing a single element, represented by its locator

form_element_locator = (By.XPATH, '//form')self.assert_screenshot(form_element_locator, screenshot_name)

• Moreover, elements can be excluded from full or element comparisons. The elements to be excluded can alsobe identified by a PageElement, a WebElement or a locator.

page_element_1 = PageElement(By.ID, 'first_id')page_element_2 = PageElement(By.ID, 'second_id')self.assert_full_screenshot(screenshot_name, exclude_elements=[page_element_1, page_→˓element_2])

• Both comparing methods have an optional parameter called threshold that marks the percentage of pixels thatare allowed to be different. It must be a number between 0 and 1.


http://toolium.readthedocs.org/en/latest/toolium.pageelements.html#module-toolium.pageelements.page_element


self.assert_full_screenshot(screenshot_name, threshold=0.1)

• They have other optional parameter called force that forces to compare the screenshot even if visual testing isdisabled by configuration. If the assertion fails, the test fails.

self.assert_full_screenshot(screenshot_name, force=True)

4.4.3 How to configure it?

Toolium properties related to Visual Testing are stored in properties.cfg

[VisualTests]enabled: truefail: falsesave: falsecomplete_report: truebaseline_name: {Driver_type}engine: pil

enabled

true: visual testing is enabled, screenshots are captured and comparedfalse: visual testing is disabled, no screenshots are captured

fail

true: if a visual assertion fails, the test failsfalse: although a visual assertion fails, the test passes

save

true: baseline images will be overwritten with new screenshotsfalse: screenshots will be compared with already saved baseline images

complete_report

true: html report will contain failed and passed visual assertionsfalse: html report will only contain failed visual assertions

baseline_name

It contains the name of the images base to compare current execution screenshots with, and it might depends on thebrowser, the mobile device or resolution used in the execution.The easiest way of generating a custom name per environment is to use the values of other configuration properties.To access a property value use the following format: {SectionName_optionName}.Some examples of baseline_name values are:

4.4. Visual Testing 27


• {Driver_type}: depending on the value of type property, baseline_name might take one of these values: firefox,iexplore, chrome. . . This is the value by default.

• {Driver_type}-{Capabilities_version}-{Capabilities_platform}: baseline_name might take one of these values:iexplore-11-WIN8, safari-9.0-YOSEMITE. . .

• {AppiumCapabilities_deviceName}-{AppiumCapabilities_platformVersion}: baseline_name might take one ofthese values: iPhone_6-8.3, iPhone_6-9.1, iPhone_6s-9.1. . .

• {PlatformVersion}: baseline_name will take the value of the mobile platform version, instead of the platfor-mVersion configuration property

• {Version}: baseline_name will take the value of version capability, although it is not configured

• {RemoteNode}: baseline_name will take the value of the remote node name

engine

Needle can compare images using different libraries (or engines) underneath. Currently, it supports Pillow,PerceptualDiff and ImageMagick.

• pil: uses Pillow to compare images. It’s the default option and it’s installed as a Toolium dependency.

• perceptualdiff : uses PerceptualDiff to compare images. It is a faster library and besides generates a diff image,highlighting the differences between the baseline image and the new screenshot. It requires to be installedseparately and depends on your host.

• imagemagick: uses ImageMagick to compare images. It also generates a diff image, highlighting the differencesin a more visual way than perceptualdiff. It requires to be installed separately and depends on your host.

4.5 Tests Result Analysis

Toolium does not create a custom tests execution report. This is delegated to your favourite test framework (unittest,nose, pytest, lettuce, behave, . . . ). But Toolium provides some useful features to analyze tests results.

4.5.1 Logs

Toolium internal logs are written in output/toolium.log. Your tests logs can be also written in the same file using thealready existing logger instance:

[TestCase or PageObject]self.logger.debug(message)

[Behave steps]context.logger.debug(message)

4.5.2 Screenshots

Toolium makes a screenshot when a test fails and saves it into the folder output/screenshots/DATE_DRIVER_TYPE.

Besides, it’s possible to make a screnshot at any time during the test and it will be saved into the same folder:


http://pdiff.sourceforge.net

http://www.imagemagick.org


[TestCase or PageObject]self.utils.capture_screenshot(screenshot_name)

[Behave steps]context.utils.capture_screenshot(screenshot_name)

4.5.3 Videos

When a test fails, Toolium downloads a video of the test execution into the folder out-put/videos/DATE_DRIVER_TYPE. This feature only works when the test has been executed in a SeleniumGrid Extras or GGR grid node. Both grids allow recording videos of test executions.

In order to download the execution video even if the test passes, configure the property video_enabled in [Server]section in properties.cfg file

[Server]video_enabled: true

video_enabled

true: remote video recording is enabled, a video of the test execution will be recorded and saved locallyfalse: remote video recording is disabled

4.5.4 Webdriver logs

When a test fails during a remote execution, Toolium downloads webdriver logs into the folder output. Depending onthe driver type, the webdriver has different log types: client, server, browser and logcat.

In order to download webdriver logs even if the test passes, configure the property logs_enabled in [Server] section inproperties.cfg file

[Server]logs_enabled: true

logs_enabled

true: webdriver and GGR logs are downloaded and saved to local files after test executionfalse: webdriver and GGR logs are downloaded and saved to local files only if the test fails

4.6 Toolium Changelog

4.6.1 v1.7.1

Release date: 2020-05-18

• Fix Appium dependency conflict, current allowed versions: from 0.24 to 0.52

4.6. Toolium Changelog 29



https://github.com/aerokube/ggr


4.6.2 v1.7.0


• Fix to allow step’s text (context.text) declaration into dynamic environment sections

• Add ssl config property in [Server] section to allow using https in Selenium Grid url

• Visual testing comparison must fail when baseline does not exist and save mode is disabled

• Update dynamic environment behaviour to work as the behave’s one, i.e. after scenario/feature actions areexecuted

even when before scenario/feature actions fail

• Fix unit tests to work without any additional dependencies

4.6.3 v1.6.1


• Fix concurrent folder creation. Add makedirs_safe method to create a new folder.

4.6.4 v1.6.0


• New config property ‘binary’ in [Chrome] section to configure the chrome binary path

• Allow configuration properties with colon in name

For instance, to set a capability with : in name, like:

goog:loggingPrefs = "{'performance': 'ALL', 'browser': 'ALL', 'driver': 'ALL'}"

Following property should be added in properties.cfg:

[Capabilities]goog___loggingPrefs: {'performance': 'ALL', 'browser': 'ALL', 'driver': 'ALL'}

• Add support for python 3.8

4.6.5 v1.5.6


• Fix dynamic environment exit code when there are hook errors

4.6.6 v1.5.5


• Fix screeninfo dependency to 0.3.1 version



4.6.7 v1.5.4


• Add support to encapsulated elements (Shadowroot)

Only support CSS_SELECTOR locatorInput text page element fixedIt is not supported for list of elements yetIt is not supported for element find by parent yetIt is not supported nested encapsulation yet

• Fix Selenium dependency conflict

4.6.8 v1.5.3


• Fix error executing Appium locally

4.6.9 v1.5.2


• Check if a GGR session (current) is still active

• Download Selenoid logs files also when test fails

• Fix utils.py wait functions’ descriptions

• Add new wait to utils.py in order to wait for an element not containing some text

4.6.10 v1.5.1


• Download Selenoid video and logs files only in linux nodes if video or logs are enabled

• Add a sleep between Selenoid retries when downloading files

• Manage exceptions in dynamic environment to mark affected scenarios as failed

4.6.11 v1.5.0


• Latest version of Appium can be used

• Make Toolium compatible with GGR and Selenoid

• Download execution video and session logs if the test fails using GGR and Selenoid

• Add logs path in the _output folder to download GGR logs

• Add username and password config properties in [Server] section to enable basic authentication in SeleniumGrid (required by GGR)



4.6.12 v1.4.3


• Fix Appium version to 0.31 or minor

4.6.13 v1.4.2


• Add movement in X axis in scroll_element_into_view method

• Fix bugs and new features in the Dynamic Environment library:

chars no utf-8 are acceptedno replace behave prefixes into a steppretty print by console, in Steps multi linesraise an exception in error caseallow comments in the steps

• Add support for python 3.7

4.6.14 v1.4.1


• Fix README.rst format to be compatible with pypi

• Fix after_scenario error when toolium before_feature is not used

• Read Config_environment before properties initialization to read right properties file

• New config section [FirefoxArguments] to set firefox arguments from properties file, e.g. ‘-private’

• Add a config property headless in [Driver] section to enable headless mode in firefox and chrome

• New config properties ‘monitor’, ‘bounds_x’ and ‘bounds_y’ in [Driver] section to configure browser boundsand monitor

• Normalize filenames to avoid errors with invalid characters

4.6.15 v1.4.0


• Add pytest fixtures to start and stop drivers

• New config property reuse_driver_session in [Driver] section to use the same driver in all tests

• Rename config property restart_driver_fail in [Driver] section to restart_driver_after_failure

• Add @no_driver feature or scenario tag to do not start the driver in these tests

• Fix output folder names when driver type is empty

• Fix output log name when Config_environment is used

• Fix Chrome options using remote drivers with Selenium >= 3.6.0



4.6.16 v1.3.0


• Add Behave dynamic environment (more info in Docs)

• Fix visual screenshot filename error when behave feature name contains :

• Add a config property ‘explicitly_wait’ in [Driver] section to set the default timeout used in wait_until methods

• When reuse_driver is true using behave, driver is initialized in before_feature method and closed in after_featuremethod

• Add @reuse_driver feature tag to reuse driver in a behave feature, even if reuse_driver is false

• Add @reset_driver scenario tag to restart driver before a behave scenario, even if reuse_driver is true

• Add is_present and is_visible methods to PageElement classes to know if an element is present or visible

4.6.17 v1.2.5


• Fix firefox initialization error using Selenium 2.X

• Add wait_until_loaded method to PageObject class to wait until all page elements with wait=True are visible

4.6.18 v1.2.4


• Fix NoSuchElementException error finding elements in nested groups

4.6.19 v1.2.3


• Save geckodriver.log file in output folder

• Fix MagickEngine name error when using an old version of needle

• Add wait_until_clickable method to Utils and PageElement classes to search for an element and wait until it isclickable

4.6.20 v1.2.2


• Fix error comparing screenshots in mobile tests

• Fix image size when enlarging a vertical image in visual testing reports

• Move js and css out of visual html report to avoid CSP errors


http://toolium.readthedocs.io/en/latest/bdd_integration.html#behave-dynamic-environment


4.6.21 v1.2.1


• Fix error installing Toolium when setuptools version is too old

4.6.22 v1.2.0


• Refactored reset_object method. Now it has an optional parameter with the driver_wrapper.

• Fix error reading geckodriver logs after test failure

• Fix error downloading videos after failed tests

• Fix error in visual tests when excluding elements in a scrolled page

• New config property ‘logs_enabled’ in [Server] section to download webdriver logs even if the test passes

• New config property ‘save_web_element’ in [Driver] section

If it’s false, the WebElement is searched whenever is needed (default value)If it’s true, the WebElement is saved in PageElement to avoid searching for the same elementmultiple times. Usefulin mobile testing when searching for an element can take a long time.

• New config property ‘restart_driver_fail’ in [Driver] section to restart the driver when the test fails even thoughthe value of reuse_driver property is true

• System property ‘Config_environment’ is used to select config files, e.g., to read android-properties.cfg file:

$ Config_environment=android nosetests web/tests/test_web.py

• Behave user property ‘env’ is deprecated, use ‘Config_environment’ instead:

$ behave -D Config_environment=android

4.6.23 v1.1.3


• Video download works in Selenium Grid 3

• New config property ‘binary’ in [Firefox] section to configure the firefox binary path

• Allow to configure visual baseline directory in ConfigFiles class (default: output/visualtests/baseline)

• Delete IE and Edge cookies after tests

• Fix wait_until_element_visible and wait_until_element_not_visible methods when the page element has a par-ent element

• Add imagemagick as visual engine to have better diff images



4.6.24 v1.1.2


• Baseline name property can contain {Version} to add actual version capability value to the baseline name

• New config property ‘gecko_driver_path’ in [Browser] section to configure the Gecko/Marionette driver location

4.6.25 v1.1.1


• Save webdriver logs of each driver, not just the first one, and only if test fails

4.6.26 v1.1.0


• New MobilePageObject class to test Android and iOS apps with the same base page objects

• Fix visual report links in Windows

• Add @no_reset_app, @reset_app and @full_reset_app behave tags to configure Appium reset capabilities forone scenario

• Add @android_only and @ios_only behave tags to exclude one scenario from iOS or Android executions

• Add a behave user property named env to select config files, e.g., to use android-properties.cfg file:

$ behave -D env=android

4.6.27 v1.0.1


• Fix wait_until_first_element_is_found error when element is None

• Fix app_strings initialization in page objects

• Fix swipe method to work with Appium 1.5 swipe

4.6.28 v1.0.0


DRIVER

• Refactor to move config property ‘browser’ in [Browser] section to ‘type’ property in [Driver] section

• Allow to run API tests with behave: driver type property must be empty

• Refactor to rename ‘driver_path’ config properties to ‘chrome_driver_path’, ‘explorer_driver_path’,‘edge_driver_path’, ‘opera_driver_path’ and ‘phantomjs_driver_path’

• Refactor to move config properties ‘reuse_driver’ and ‘implicitly_wait’ from [Common] section to [Driver]section

• Add a new config property ‘appium_app_strings’ in [Driver] section to request app strings before each Appiumtest



• Add new config properties ‘window_width’ and ‘window_height’ in [Driver] section to configure browser win-dow size

• Upload the error screenshot to Jira if the test fails

• Allow to add extensions to firefox profile from properties file

New config section [FirefoxExtensions] with extensions file paths, e.g. ‘firebug = firebug-3.0.0-beta.3.xpi’

• Allow to use a predefined firefox profile

New config property ‘profile’ in [Firefox] section to configure the profile directory

• Allow to set chrome arguments from properties file

New config section [ChromeArguments] with chrome arguments, e.g. ‘lang = es’

PAGE OBJECTS

• Save WebElement in PageElement to avoid searching for the same element multiple times

• Refactor to rename get_element to get_web_element in Utils class and element to web_element in PageElementclass

• Add wait_until_first_element_is_found method to Utils class to search for a list of elements and wait until oneof them is found

• Add new page element types: Checkbox, InputRadio, Link, Group and PageElements

BEHAVE

• Allow to modify Toolium properties from behave userdata configuration, e.g.:

$ behave -D Driver_type=chrome

VISUAL TESTING

• Refactor to rename assertScreenshot to assert_screenshot and assertFullScreenshot to assert_full_screenshot

• Add force parameter to assert_screenshot methods to compare the screenshot even if visual testing is disabledby configuration. If the assertion fails, the test fails.

• Baseline name property can contain {PlatformVersion} or {RemoteNode} to add actual platform version or re-mote node name to the baseline name

4.6.29 v0.12.1


• Fix app_strings initialization in Behave Appium tests

• In Behave tests, Toolium config is saved in context.toolium_config instead of using context.config to avoidoverriding Behave config

4.6.30 v0.12.0


• Allow to create a second driver using DriverWrapper constructor:



second_wrapper = DriverWrapper()second_wrapper.connect()

• Fix page object issue with non-default driver. Now page object and utils init methods have both a driver_wrapperoptional parameter instead of driver parameter.

• Fix swipe over an element in Android and iOS web tests

• Move set_config_* and set_output_* test case methods to ConfigFiles class

• Add behave environment file to initialize Toolium wrapper from behave tests

4.6.31 v0.11.3


• Fix image size in visual testing for Android and iOS web tests

• Baseline name property allows any configuration property value to configure the visual testing baseline folder,e.g.:

{AppiumCapabilities_deviceName}-{AppiumCapabilities_platformVersion}: this baseline_namecould use baselines as iPhone_6-8.3, iPhone_6-9.1, iPhone_6s-9.1, . . .{Browser_browser}: this baseline_name could use baselines as firefox, iexplore, . . . (default value)

• Fix page elements initialization when they are defined outside of a page object

4.6.32 v0.11.2


• Compatibility with Python 3

4.6.33 v0.11.1


• New config property ‘operadriver_path’ in [Browser] section to configure the Opera Driver location

• Fix initialization error when a page object contains another page object

• Fix visual testing error if browser is phantomjs

• Fix firefox profile error in remote executions

• Configure setup.py to execute tests with ‘python setup.py test’

• Convert markdown (.md) files to reStructuredText (.rst) and update long_description with README.rst content

4.6.34 v0.11.0


• Rename library from seleniumtid to toolium

• Distributed under Apache Software License, Version 2



4.6.35 v0.10.0


• Add support to Edge Windows browser

• New config property ‘summary_prefix’ in [Jira] section to modify default TCE summary

• Add scroll_element_into_view method to PageElement that scroll to element

• Add parent parameter to PageElement when element must be found from parent

• Page elements can be defined as class attributes, it is no longer necessary to define them as instance attributes ininit_page_elements()

• Add wait_until_visible, wait_until_not_visible and assertScreenshot methods to PageElement

• Allow to set Chrome mobile options from properties file

New config section [ChromeMobileEmulation] with mobile emulation options, e.g. ‘deviceName =Google Nexus 5’

• Configuration system properties has been renamed

Old properties: Files_output_path, Files_log_filename, Files_properties, Files_loggingNew properties: Output_directory, Output_log_filename, Config_directory, Config_prop_filenames,Config_log_filename

• Add set_config_* and set_output_* test case methods to configure output and config files instead of usingconfiguration system properties

4.6.36 v0.9.3


• Allow to set custom driver capabilities from properties file

New config section [Capabilities] with driver capabilities

• Fix set_value and app_strings errors in mobile web tests

• Fix set_value error in iOS tests when using needle

4.6.37 v0.9.2


• Allow to find elements by ios_uiautomation in visual assertions

• Fix app_strings error in mobile web tests

• Use set_value instead of send_keys to run tests faster

4.6.38 v0.9.1


• Add swipe method in Utils to allow swipe over an element

• Only one property file is mandatory if Files_properties has multiple values

• Allow to exclude elements from visual screenshots



4.6.39 v0.9.0


• Output path (screenshots, videos, visualtests) can be specified with a system property: Files_output_path

• Update app_strings in Appium tests only if the driver has changed

• Move visual properties from [Server] section to [VisualTests] section

• With a visual assertion error, the test can fail or give an error message and continue

New config property ‘fail’ in [VisualTests] section to fail the test when there is a visual error

• Create a html report with the visual tests results

New config property ‘complete_report’ in [VisualTests] section to include also correct visual asser-tions in report

• Configure multiple baseline name for different browsers, languages and versions

New config property ‘baseline_name’ in [VisualTests] section to configure the name of the baselinefolderAllow {browser}, {language} and {platformVersion} variables, e.g. baseline_name ={browser}-{language}The default baseline_name is {browser}.

• Add assertFullScreenshot method in SeleniumTestCase

4.6.40 v0.8.6


• Add wait_until_element_visible method in utils class

• Logger filename can be specified with a system property: Files_log_filename

4.6.41 v0.8.5


• Add Button page element

• AppiumTestCase has a new attribute app_strings, a dict with application strings in the active language

4.6.42 v0.8.4


• Allow to set firefox and chrome preferences from properties file

New config section [FirefoxPreferences] with firefox preferences, e.g. ‘browser.download.dir =/tmp’New config section [ChromePreferences] with chrome preferences, e.g.‘download.default_directory = /tmp’



4.6.43 v0.8.3


• Read properties file before each test to allow executing tests with different configurations (android, iphone, . . . )

4.6.44 v0.8.2


• Logging and properties config files can be specified with a system property: Files_logging and Files_properties

Files_properties allows multiple files separated by ;

4.6.45 v0.8.1


• Fixed minor bugs

• Add visual testing to lettuce tests

4.6.46 v0.8


• Add visual testing to SeleniumTestCase and AppiumTestCase

New config property ‘visualtests_enabled’ in [Server] section to enable visual testingNew config property ‘visualtests_save’ in [Server] section to overwrite baseline images with actualscreenshotsNew config property ‘visualtests_engine’ in [Server] section to select image engine (pil orperceptualdiff)

4.6.47 v0.7


• Allow to autocomplete self.driver and self.utils in IDEs

• Remove non-mandatory requirements

4.6.48 v0.6


• Multiple tests of a class can be linked to the same Jira Test Case

• If test fails, the error message will be added as a comment to the Jira Test Case Execution

• Update Jira Test Cases also in lettuce tests



4.6.49 v0.5


• Downloads the saved video if the test has been executed in a VideoGrid

• Add BasicTestCase class to be used in Api tests or in other tests without selenium driver

4.6.50 v0.4


• Add Lettuce terrain file to initialize Selenium driver

• Add ConfigDriver.create_driver method to create a new driver with specific configuration

• Add wait_until_element_not_visible method in utils class

4.6.51 v0.3


• Add a config property ‘implicitly_wait’ in [Common] section to set an implicit timeout

• Add a config property ‘reuse_driver’ in [Common] section to use the same driver in all tests of each class

• The driver can be reused only in a test class setting a class variable ‘reuse_driver = True’

4.6.52 v0.2


• Now depends on Appium 1.0

4.6.53 v0.1


• First version of the selenium library in python

4.7 toolium packages

4.7.1 behave

environment

toolium.behave.environment.add_assert_screenshot_methods(context_or_world, sce-nario)

Add assert screenshot methods to behave or lettuce object

Parameters

• context_or_world – behave context or lettuce world

• scenario – running scenario

4.7. toolium packages 41


toolium.behave.environment.after_all(context)Clean method that will be executed after all features are finished

Parameters context – behave context

toolium.behave.environment.after_feature(context, feature)Clean method that will be executed after each feature

Parameters

• context – behave context

• feature – running feature

toolium.behave.environment.after_scenario(context, scenario)Clean method that will be executed after each scenario

Parameters



toolium.behave.environment.bdd_common_after_all(context_or_world)Common after all method in behave or lettuce

Parameters context_or_world – behave context or lettuce world

toolium.behave.environment.bdd_common_after_scenario(context_or_world, scenario,status)

Clean method that will be executed after each scenario in behave or lettuce

Parameters



• status – scenario status (passed, failed or skipped)

toolium.behave.environment.bdd_common_before_scenario(context_or_world, scenario,no_driver=False)

Common scenario initialization in behave or lettuce

Parameters



• no_driver – True if this is an api test and driver should not be started

toolium.behave.environment.before_all(context)Initialization method that will be executed before the test execution

Parameters context – behave context

toolium.behave.environment.before_feature(context, feature)Feature initialization

Parameters


• feature – running feature

toolium.behave.environment.before_scenario(context, scenario)Scenario initialization



Parameters



toolium.behave.environment.connect_wrapper(context_or_world)Connect driver in behave or lettuce tests


toolium.behave.environment.create_and_configure_wrapper(context_or_world)Create and configure driver wrapper in behave or lettuce tests


toolium.behave.environment.get_jira_key_from_scenario(scenario)Extract Jira Test Case key from scenario tags. Two tag formats are allowed: @jira(‘PROJECT-32’)@jira=PROJECT-32

Parameters scenario – behave scenario

Returns Jira test case key

toolium.behave.environment.install_pytest_asserts()

toolium.behave.environment.start_driver(context, no_driver)Start driver with configured values

Parameters


• no_driver – True if this is an api test and driver should not be started

4.7.2 lettuce

terrain

4.7.3 pageelements

page_element

class toolium.pageelements.page_element.PageElement(by, value, parent=None, or-der=None, wait=False, shadow-root=None)

Bases: toolium.pageobjects.common_object.CommonObject

Class to represent a web or a mobile page element

assert_screenshot(filename, threshold=0, exclude_elements=[], force=False)Assert that a screenshot of the element is the same as a screenshot on disk, within a given threshold.

Parameters

• filename – the filename for the screenshot, which will be appended with .png

• threshold – percentage threshold for triggering a test failure (value between 0 and 1)

• exclude_elements – list of WebElements, PageElements or element locators as atuple (locator_type, locator_value) that must be excluded from the assertion



• force – if True, the screenshot is compared even if visual testing is disabled by configu-ration

driver_wrapper = Nonedriver wrapper instance

get_attribute(name)Get the given attribute or property of the element

Parameters name – name of the attribute/property to retrieve

Returns attribute value

is_present()Find element and return True if it is present

Returns True if element is located

is_visible()Find element and return True if it is visible

Returns True if element is visible

locator = Nonetuple with locator type and locator value

order = Noneindex value if the locator returns more than one element

parent = Noneelement from which to find actual elements

reset_object(driver_wrapper=None)Reset each page element object

Parameters driver_wrapper – driver wrapper instance

scroll_element_into_view()Scroll element into view

Returns page element instance

shadowroot = NoneCSS SELECTOR of the shadowroot for encapsulated element

wait = NoneTrue if it must be loaded in wait_until_loaded method of the container page object

wait_until_clickable(timeout=None)Search element and wait until it is clickable

Parameters timeout – max time to wait


wait_until_not_visible(timeout=None)Search element and wait until it is not visible



wait_until_visible(timeout=None)Search element and wait until it is visible





web_elementFind WebElement using element locator

Returns web element object

Return type selenium.webdriver.remote.webelement.WebElement or ap-pium.webdriver.webelement.WebElement

button_page_element

class toolium.pageelements.button_page_element.Button(by, value, parent=None, or-der=None, wait=False, shad-owroot=None)

Bases: toolium.pageelements.page_element.PageElement

click()Click the element


textGet the element text value

Returns element text value

checkbox_page_element

class toolium.pageelements.checkbox_page_element.Checkbox(by, value, par-ent=None, or-der=None, wait=False,shadowroot=None)

Bases: toolium.pageelements.button_page_element.Button

check()Select the checkbox


is_selected()Returns whether the element is selected

Returns true whether the element is selected



uncheck()Uncheck the checkbox




group_page_element

class toolium.pageelements.group_page_element.Group(by, value, parent=None,driver_wrapper=None, or-der=None, wait=False)

Bases: toolium.pageobjects.page_object.PageObject, toolium.pageelements.page_element.PageElement



logger = Nonelogger instance





shadowroot = NoneNot implemented for PAgeElements yet


input_radio_page_element

class toolium.pageelements.input_radio_page_element.InputRadio(by, value,parent=None,order=None,wait=False,shadow-root=None)


check()Select the radio button


is_selected()Returns whether the element is selected

Returns true whether the element is selected





input_text_page_element

class toolium.pageelements.input_text_page_element.InputText(by, value, par-ent=None,order=None,wait=False, shad-owroot=None)


clear()Clear the element value




link_page_element

class toolium.pageelements.link_page_element.Link(by, value, parent=None, or-der=None, wait=False, shadow-root=None)


hrefGet the href value of the link element

Returns href value

select_page_element

class toolium.pageelements.select_page_element.Select(by, value, parent=None, or-der=None, wait=False, shad-owroot=None)


optionReturn text of the first selected option

Returns first selected option text

selenium_selectReturn Selenium select object to call other select methods, like select_by_index, deselect_by_index. . .

Returns Selenium select object

text_page_element

class toolium.pageelements.text_page_element.Text(by, value, parent=None, or-der=None, wait=False, shadow-root=None)


textGet the text of the element

Returns the text of the element



page_elements

class toolium.pageelements.page_elements.Buttons(by, value, parent=None,page_element_class=None, or-der=None)

Bases: toolium.pageelements.page_elements.PageElements

page_element_classalias of toolium.pageelements.button_page_element.Button

class toolium.pageelements.page_elements.Checkboxes(by, value, parent=None,page_element_class=None,order=None)


page_element_classalias of toolium.pageelements.checkbox_page_element.Checkbox

class toolium.pageelements.page_elements.Groups(by, value, parent=None,page_element_class=None, or-der=None)


page_element_classalias of toolium.pageelements.group_page_element.Group

class toolium.pageelements.page_elements.InputRadios(by, value, parent=None,page_element_class=None,order=None)


page_element_classalias of toolium.pageelements.input_radio_page_element.InputRadio

class toolium.pageelements.page_elements.InputTexts(by, value, parent=None,page_element_class=None,order=None)


page_element_classalias of toolium.pageelements.input_text_page_element.InputText

class toolium.pageelements.page_elements.Links(by, value, parent=None,page_element_class=None, or-der=None)


page_element_classalias of toolium.pageelements.link_page_element.Link

class toolium.pageelements.page_elements.PageElements(by, value, parent=None,page_element_class=None,order=None)

Bases: toolium.pageobjects.common_object.CommonObject

Class to represent multiple web or mobile page elements






page_element_classalias of toolium.pageelements.page_element.PageElement

page_elementsFind multiple PageElement using element locator

Returns list of page element objects

Return type list of toolium.pageelements.PageElement




shadowroot = NoneNot implemented for PAgeElements yet

web_elementsFind multiple WebElements using element locator

Returns list of web element objects

Return type list of selenium.webdriver.remote.webelement.WebElement or list of ap-pium.webdriver.webelement.WebElement

class toolium.pageelements.page_elements.Selects(by, value, parent=None,page_element_class=None, or-der=None)


page_element_classalias of toolium.pageelements.select_page_element.Select

class toolium.pageelements.page_elements.Texts(by, value, parent=None,page_element_class=None, or-der=None)


page_element_classalias of toolium.pageelements.text_page_element.Text

4.7.4 pageobjects

page_object

class toolium.pageobjects.page_object.PageObject(driver_wrapper=None, wait=False)Bases: toolium.pageobjects.common_object.CommonObject

Class to represent a web page or a mobile application screen




init_page_elements()Method to initialize page elements

This method can be overridden to define page elements and will be called in page object __init__




wait_until_loaded(timeout=None)Wait until page object is loaded Search all page elements configured with wait=True


Returns this page object instance

common_object

class toolium.pageobjects.common_object.CommonObjectBases: object

Base class for page objects and page elements

configGet config instance

Returns config instance

driverGet driver instance

Returns driver instance



reset_object()Method to reset this object. This method can be overridden to define specific functionality.

utilsGet utils instance

Returns utils instance

mobile_page_object

class toolium.pageobjects.mobile_page_object.MobilePageObject(driver_wrapper=None,wait=False)

Bases: toolium.pageobjects.page_object.PageObject


https://docs.python.org/3/library/functions.html#object


4.8 toolium modules

4.8.1 config_driver

class toolium.config_driver.ConfigDriver(config, utils=None)Bases: object

create_driver()Create a selenium driver using specified config properties

Returns a new selenium driver

Return type selenium.webdriver.remote.webdriver.WebDriver

toolium.config_driver.get_error_message_from_exception(exception)Extract first line of exception message

Parameters exception – exception object

Returns first line of exception message

4.8.2 config_files

class toolium.config_files.ConfigFiles

set_config_directory(config_directory)Set directory where configuration files are saved

Parameters config_directory – configuration directory path

set_config_log_filename(filename)Set logging configuration file

Parameters filename – logging configuration filename

set_config_properties_filenames(*filenames)Set properties files used to configure test cases

Parameters filenames – list of properties filenames

set_output_directory(output_directory)Set output directory where log file and screenshots will be saved

Parameters output_directory – output directory path

set_output_log_filename(filename)Set logging output file

Parameters filename – logging configuration filename

set_visual_baseline_directory(visual_baseline_directory)Set visual baseline directory where baseline images will be saved

Parameters visual_baseline_directory – visual baseline directory path

4.8. toolium modules 51



4.8.3 config_parser

class toolium.config_parser.ExtendedConfigParser(defaults=None, dict_type=<class’collections.OrderedDict’>, al-low_no_value=False)

Bases: ConfigParser.ConfigParser

deepcopy()Returns a deep copy of config object

Returns a copy of the config object

static get_config_from_file(conf_properties_files)Reads properties files and saves them to a config object

Parameters conf_properties_files – comma-separated list of properties files

Returns config object

get_optional(section, option, default=None)Get an option value for a given section If the section or the option are not found, the default value isreturned

Parameters

• section – config section

• option – config option

• default – default value

Returns config value

getboolean_optional(section, option, default=False)Get an option boolean value for a given section If the section or the option are not found, the default valueis returned

Parameters

• section – config section

• option – config option

• default – default value

Returns boolean config value

optionxform(optionstr)Override default optionxform in ConfigParser

update_properties(new_properties)Update config properties values Property name must be equal to ‘Section_option’ of config property

Parameters new_properties – dict with new properties values

4.8.4 driver_wrapper

class toolium.driver_wrapper.DriverWrapperBases: object

Wrapper with the webdriver and the configuration needed to execute tests




app_strings = Nonemobile application strings

baseline_name = Nonebaseline name

config = <toolium.config_parser.ExtendedConfigParser instance>driver configuration

config_log_filename = Noneconfiguration log file

config_properties_filenames = Noneconfiguration filenames separated by commas

configure(tc_config_files, is_selenium_test=True, behave_properties=None)Configure initial selenium instance using logging and properties files for Selenium or Appium tests

Parameters

• tc_config_files – test case specific config files

• is_selenium_test – true if test is a selenium or appium test case

• behave_properties – dict with behave user data properties

configure_logger(tc_config_log_filename=None, tc_output_log_filename=None)Configure selenium instance logger

Parameters

• tc_config_log_filename – test case specific logging config file

• tc_output_log_filename – test case specific output logger file

configure_properties(tc_config_prop_filenames=None, behave_properties=None)Configure selenium instance properties

Parameters

• tc_config_prop_filenames – test case specific properties filenames

• behave_properties – dict with behave user data properties

configure_visual_baseline()Configure baseline directory

connect(maximize=True)Set up the selenium driver and connect to the server

Parameters maximize – True if the driver should be maximized

Returns selenium driver

driver = Nonewebdriver instance

get_config_window_bounds()Reads bounds from config and, if monitor is specified, modify the values to match with the specifiedmonitor

Returns coords X and Y where set the browser window.

get_driver_platform()Get driver platform where tests are running :return: platform name



is_android_test()Check if actual test must be executed in an Android mobile

Returns True if test must be executed in an Android mobile

is_android_web_test()Check if actual test must be executed in a browser of an Android mobile

Returns True if test must be executed in a browser of an Android mobile

is_ios_test()Check if actual test must be executed in an iOS mobile

Returns True if test must be executed in an iOS mobile

is_ios_web_test()Check if actual test must be executed in a browser of an iOS mobile

Returns True if test must be executed in a browser of an iOS mobile

is_maximizable()Check if the browser is maximizable

Returns True if the browser is maximizable

is_mobile_test()Check if actual test must be executed in a mobile

Returns True if test must be executed in a mobile

is_web_test()Check if actual test must be executed in a browser

Returns True if test must be executed in a browser


output_log_filename = Noneoutput log file

remote_node = Noneremote grid node

remote_node_video_enabled = FalseTrue if the remote grid node has the video recorder enabled

server_type = Noneremote server type

session_id = Noneremote webdriver session id

should_reuse_driver(scope, test_passed, context=None)Check if the driver should be reused

Parameters

• scope – execution scope (function, module, class or session)

• test_passed – True if the test has passed


Returns True if the driver should be reused



update_magic_config_names()Replace ‘___’ for ‘:’ in options names as a workaround of a configparser limitation To set a config propertywith : in name

goog:loggingPrefs = “{‘performance’: ‘ALL’, ‘browser’: ‘ALL’, ‘driver’: ‘ALL’}”

Configure properties.cfg with: goog___loggingPrefs: {‘performance’: ‘ALL’, ‘browser’: ‘ALL’,‘driver’: ‘ALL’}

update_visual_baseline()Configure baseline directory after driver is created

utils = Nonetest utils instance

visual_baseline_directory = Nonefolder with the baseline images

4.8.5 driver_wrappers_pool

class toolium.driver_wrappers_pool.DriverWrappersPoolBases: object

Driver wrappers pool

classmethod add_wrapper(driver_wrapper)Add a driver wrapper to the wrappers pool

Parameters driver_wrapper – driver_wrapper instance

classmethod capture_screenshots(name)Capture a screenshot in each driver

Parameters name – screenshot name suffix

classmethod close_drivers(scope, test_name, test_passed=True, context=None)Stop all drivers, capture screenshots, copy webdriver and GGR logs and download saved videos

Parameters

• scope – execution scope (function, module, class or session)

• test_name – executed test name



config_directory = Nonefolder with configuration files

classmethod configure_common_directories(tc_config_files)Configure common config and output folders for all tests

Parameters tc_config_files – test case specific config files

classmethod configure_visual_directories(driver_info)Configure screenshots, videos and visual directories

Parameters driver_info – driver property value to name folders




classmethod connect_default_driver_wrapper(config_files=None)Get default driver wrapper, configure it and connect driver

Parameters config_files – driver wrapper specific config files

Returns default driver wrapper

Return type toolium.driver_wrapper.DriverWrapper

classmethod download_videos(name, test_passed=True, maintain_default=False)Download saved videos if video is enabled or if test fails

Parameters

• name – destination file name


• maintain_default – True if the default driver should not be closed

driver_wrappers = []driver wrappers list

static get_configured_value(system_property_name, specific_value, default_value)Get configured value from system properties, method parameters or default value

Parameters

• system_property_name – system property name

• specific_value – test case specific value

• default_value – default value

Returns configured value

static get_default_config_directory()Return default config directory, based in the actual test path

Returns default config directory

classmethod get_default_wrapper()Returns the default (first) driver wrapper

Returns default driver wrapper

Return type toolium.driver_wrapper.DriverWrapper

static initialize_config_files(tc_config_files=None)Initialize config files and update config files names with the environment

Parameters tc_config_files – test case specific config files

Returns initialized config files object

classmethod is_empty()Check if the wrappers pool is empty

Returns true if the wrappers pool is empty

logs_directory = Nonefolder to save logs

output_directory = Nonefolder to save output files

classmethod remove_drivers(maintain_default=False)Clean drivers list except default if it should be reused. Drivers must be closed before.



Parameters maintain_default – True if the default driver should not be removed

classmethod save_all_ggr_logs(test_name, test_passed)Get all GGR logs of each driver and write them to log files

Parameters

• test_name – test that has generated these logs


classmethod save_all_webdriver_logs(test_name, test_passed)Get all webdriver logs of each driver and write them to log files

Parameters



screenshots_directory = Nonefolder to save screenshots

screenshots_number = Nonenumber of screenshots taken until now

classmethod stop_drivers(maintain_default=False)Stop all drivers except default if it should be reused

Parameters maintain_default – True if the default driver should not be closed

videos_directory = Nonefolder to save videos

videos_number = Nonenumber of visual images taken until now

visual_baseline_directory = Nonefolder to save visual baseline images

visual_number = Nonenumber of videos recorded until now

visual_output_directory = Nonefolder to save visual report and images

4.8.6 jira

toolium.jira.add_attachment(attachment)Add a file path to attachments list

Parameters attachment – attachment file path

toolium.jira.add_jira_status(test_key, test_status, test_comment)Save test status and comments to update Jira later

Parameters

• test_key – test case key in Jira

• test_status – test case status

• test_comment – test case comments



toolium.jira.change_all_jira_status()Iterate over all jira test cases, update their status in Jira and clear the dictionary

toolium.jira.change_jira_status(test_key, test_status, test_comment, test_attachments)Update test status in Jira

Parameters

• test_key – test case key in Jira

• test_status – test case status

• test_comment – test case comments

• test_attachments – test case attachments

toolium.jira.get_error_message(response_content)Extract error message from the HTTP response

Parameters response_content – HTTP response from test case execution API

Returns error message

toolium.jira.jira(test_key)Decorator to update test status in Jira

Parameters test_key – test case key in Jira

Returns jira test

toolium.jira.save_jira_conf()Read Jira configuration from properties file and save it

4.8.7 test_cases

class toolium.test_cases.AppiumTestCase(methodName=’runTest’)Bases: toolium.test_cases.SeleniumTestCase

A class whose instances are Appium test cases.

Attributes: app_strings: dict with application strings

app_strings = None

driver

Get the Appium driver This method allows to autocomplete self.driver in IDEs

Returns Appium driver

Return type appium.webdriver.webdriver.WebDriver

setUp()Hook method for setting up the test fixture before exercising it.

class toolium.test_cases.BasicTestCase(methodName=’runTest’)Bases: unittest.case.TestCase

A class whose instances are api test cases.

config_files = <toolium.config_files.ConfigFiles instance>

driver_wrapper = None

get_method_name()



classmethod get_subclass_name()

get_subclassmethod_name()


tearDown()Hook method for deconstructing the test fixture after testing it.

classmethod tearDownClass()Hook method for deconstructing the class fixture after running all tests in the class.

class toolium.test_cases.SeleniumTestCase(methodName=’runTest’)Bases: toolium.test_cases.BasicTestCase

A class whose instances are Selenium test cases.

Attributes: driver: webdriver instance utils: test utils instance

assert_full_screenshot(filename, threshold=0, exclude_elements=[], driver_wrapper=None,force=False)

Assert that a driver screenshot is the same as a screenshot on disk, within a given threshold.

Parameters



• exclude_elements – list of CSS/XPATH selectors as a string or WebElement objectsthat must be excluded from the assertion.

• driver_wrapper – driver wrapper instance


assert_screenshot(element, filename, threshold=0, exclude_elements=[], driver_wrapper=None,force=False)

Assert that a screenshot of an element is the same as a screenshot on disk, within a given threshold.

Parameters

• element – either a WebElement, PageElement or element locator as a tuple (loca-tor_type, locator_value). If None, a full screenshot is taken.



• exclude_elements – list of CSS/XPATH selectors as a string or WebElement objectsthat must be excluded from the assertion.

• driver_wrapper – driver wrapper instance


driver = None




tearDown()Hook method for deconstructing the test fixture after testing it.

classmethod tearDownClass()Hook method for deconstructing the class fixture after running all tests in the class.

utils = None

4.8.8 utils

class toolium.utils.Utils(driver_wrapper=None)Bases: object

capture_screenshot(name)Capture screenshot and save it in screenshots folder

Parameters name – screenshot name suffix

Returns screenshot path

discard_logcat_logs()Discard previous logcat logs

download_remote_video(remote_node, session_id, video_name)Download the video recorded in the remote node during the specified test session and save it in videosfolder

Parameters

• remote_node – remote node name

• session_id – test session id

• video_name – video name

get_center(element)Get center coordinates of an element

Parameters element – either a WebElement, PageElement or element locator as a tuple (lo-cator_type, locator_value)

Returns dict with center coordinates

get_explicitly_wait()Read explicitly timeout from configuration properties

Returns configured explicitly timeout (default timeout 10 seconds)

get_first_webview_context()Return the first WEBVIEW context or raise an exception if it is not found

Returns first WEBVIEW context

get_implicitly_wait()Read implicitly timeout from configuration properties

get_native_coords(coords)

Convert web coords into native coords. Assumes that the initial context is WEBVIEW and switches toNATIVE_APP context.

Parameters coords – dict with web coords, e.g. {‘x’: 10, ‘y’: 10}

Returns dict with native coords




get_remote_node()Return the remote node that it’s executing the actual test session

Returns tuple with server type (local, grid, ggr, selenium) and remote node name

get_safari_navigation_bar_height()Get the height of Safari navigation bar

Returns height of navigation bar

get_server_url()Return the configured server url

Returns server url

get_web_element(element)Return the web element from a page element or its locator

Parameters element – either a WebElement, PageElement or element locator as a tuple (lo-cator_type, locator_value)

Returns WebElement object

get_window_size()Generic method to get window size using a javascript workaround for Android web tests

Returns dict with window width and height

is_remote_video_enabled(remote_node)Check if the remote node has the video recorder enabled

Parameters remote_node – remote node name

Returns true if it has the video recorder enabled

save_webdriver_logs(test_name)Get webdriver logs and write them to log files

Parameters test_name – test that has generated these logs

save_webdriver_logs_by_type(log_type, test_name)Get webdriver logs of the specified type and write them to a log file

Parameters

• log_type – browser, client, driver, performance, server, syslog, crashlog or logcat


set_implicitly_wait()Read implicitly timeout from configuration properties and configure driver implicitly wait

swipe(element, x, y, duration=None)Swipe over an element

Parameters

• element – either a WebElement, PageElement or element locator as a tuple (loca-tor_type, locator_value)

• x – horizontal movement

• y – vertical movement

• duration – time to take the swipe, in ms



switch_to_first_webview_context()Switch to the first WEBVIEW context

wait_until_element_attribute_is(element, attribute, value, timeout=None)Search element and wait until the requested attribute contains the expected value

Parameters

• element – PageElement or element locator as a tuple (locator_type, locator_value) to befound

• attribute – attribute belonging to the element

• value – expected value for the attribute of the element

• timeout – max time to wait

Returns the web element if the element’s attribute contains the expected value


Raises TimeoutException – If the element’s attribute does not contain the expected valueafter the timeout

wait_until_element_clickable(element, timeout=None)Search element and wait until it is clickable

Parameters



Returns the web element if it is clickable


Raises TimeoutException – If the element is not clickable after the timeout

wait_until_element_contains_text(element, text, timeout=None)Search element and wait until it contains the expected text

Parameters


• text – text expected to be contained into the element


Returns the web element if it contains the expected text


Raises TimeoutException – If the element does not contain the expected text after thetimeout

wait_until_element_not_contain_text(element, text, timeout=None)Search element and wait until it does not contain the expected text

Parameters




• text – text expected to be contained into the element


Returns the web element if it does not contain the given text


Raises TimeoutException – If the element contains the expected text after the timeout

wait_until_element_not_visible(element, timeout=None)Search element and wait until it is not visible

Parameters



Returns the web element if it exists but is not visible


Raises TimeoutException – If the element is still visible after the timeout

wait_until_element_present(element, timeout=None)Search element and wait until it is found

Parameters



Returns the web element if it is present


Raises TimeoutException – If the element is not found after the timeout

wait_until_element_stops(element, times=1000, timeout=None)Search element and wait until it has stopped moving

Parameters


• times – number of iterations checking the element’s location that must be the same forall of them

in order to considering the element has stopped :returns: the web element if the element is stopped :rtype:selenium.webdriver.remote.webelement.WebElement or appium.webdriver.webelement.WebElement:raises TimeoutException: If the element does not stop after the timeout

wait_until_element_visible(element, timeout=None)Search element and wait until it is visible

Parameters





Returns the web element if it is visible


Raises TimeoutException – If the element is still not visible after the timeout

wait_until_first_element_is_found(elements, timeout=None)Search list of elements and wait until one of them is found

Parameters

• elements – list of PageElements or element locators as a tuple (locator_type, loca-tor_value) to be found sequentially


Returns first element found

Return type toolium.pageelements.PageElement or tuple

Raises TimeoutException – If no element in the list is found after the timeout

4.8.9 visual_test

class toolium.visual_test.VisualTest(driver_wrapper=None, force=False)Bases: object

Visual testing class

assert_screenshot(element, filename, file_suffix=None, threshold=0, exclude_elements=[])Assert that a screenshot of an element is the same as a screenshot on disk, within a given threshold

Parameters

• element – either a WebElement, PageElement or element locator as a tuple (loca-tor_type, locator_value). If None, a full screenshot is taken.


• file_suffix – a string to be appended to the output filename with extra info about thetest.


• exclude_elements – list of WebElements, PageElements or element locators as atuple (locator_type, locator_value) that must be excluded from the assertion

compare_files(report_name, image_file, baseline_file, threshold)Compare two image files and add result to the html report

Parameters

• report_name – name to show in html report

• image_file – image file path

• baseline_file – baseline image file path


https://docs.python.org/3/library/stdtypes.html#tuple



• threshold – percentage threshold

Returns error message

crop_element(img, web_element)Crop image to fit element

Parameters

• img – image object

• web_element – WebElement object

Returns modified image object

css_name = 'VisualTests.css'name of the css file


exclude_elements(img, web_elements)Modify image hiding elements with a black rectangle

Parameters

• img – image object

• web_elements – WebElement objects to be excluded

force = Falseif True, screenshot is compared even if visual testing is disabled by configuration

get_element_box(web_element)Get element coordinates

Parameters web_element – WebElement object

Returns tuple with element coordinates

get_scrolls_size()Return Chrome and Explorer scrolls sizes if they are visible Firefox screenshots don’t contain scrolls

Returns dict with horizontal and vertical scrolls sizes

javascript_name = 'VisualTests.js'name of the javascript file

mobile_resize(img)Resize image in iOS (native and web) and Android (web) to fit window size

Parameters img – image object


remove_scrolls(img)Remove browser scrolls from image if they are visible

Parameters img – image object


report_name = 'VisualTests.html'final visual report name

results = {'baseline': 0, 'diff': 0, 'equal': 0}dict to save visual assert results



template_name = 'VisualTestsTemplate.html'name of the report template


CHAPTER 5

Indices and Tables

• genindex

• modindex

• search

67


68 Chapter 5. Indices and Tables

Python Module Index

ttoolium.behave.environment, 41toolium.config_driver, 51toolium.config_files, 51toolium.config_parser, 52toolium.driver_wrapper, 52toolium.driver_wrappers_pool, 55toolium.jira, 57toolium.pageelements.button_page_element,

45toolium.pageelements.checkbox_page_element,

45toolium.pageelements.group_page_element,

46toolium.pageelements.input_radio_page_element,

46toolium.pageelements.input_text_page_element,

47toolium.pageelements.link_page_element,

47toolium.pageelements.page_element, 43toolium.pageelements.page_elements, 48toolium.pageelements.select_page_element,

47toolium.pageelements.text_page_element,

47toolium.pageobjects.common_object, 50toolium.pageobjects.mobile_page_object,

50toolium.pageobjects.page_object, 49toolium.test_cases, 58toolium.utils, 60toolium.visual_test, 64

69


70 Python Module Index

Index

Aadd_assert_screenshot_methods() (in mod-

ule toolium.behave.environment), 41add_attachment() (in module toolium.jira), 57add_jira_status() (in module toolium.jira), 57add_wrapper() (toolium.driver_wrappers_pool.DriverWrappersPool

class method), 55after_all() (in module

toolium.behave.environment), 41after_feature() (in module

toolium.behave.environment), 42after_scenario() (in module

toolium.behave.environment), 42app_strings (toolium.driver_wrapper.DriverWrapper

attribute), 52app_strings (toolium.test_cases.AppiumTestCase at-

tribute), 58AppiumTestCase (class in toolium.test_cases), 58assert_full_screenshot()

(toolium.test_cases.SeleniumTestCase method),59

assert_screenshot()(toolium.pageelements.page_element.PageElementmethod), 43

assert_screenshot()(toolium.test_cases.SeleniumTestCase method),59

assert_screenshot()(toolium.visual_test.VisualTest method),64

Bbaseline_name (toolium.driver_wrapper.DriverWrapper

attribute), 53BasicTestCase (class in toolium.test_cases), 58bdd_common_after_all() (in module

toolium.behave.environment), 42bdd_common_after_scenario() (in module

toolium.behave.environment), 42

bdd_common_before_scenario() (in moduletoolium.behave.environment), 42

before_all() (in moduletoolium.behave.environment), 42

before_feature() (in moduletoolium.behave.environment), 42

before_scenario() (in moduletoolium.behave.environment), 42

Button (class in toolium.pageelements.button_page_element),45

Buttons (class in toolium.pageelements.page_elements),48

Ccapture_screenshot() (toolium.utils.Utils

method), 60capture_screenshots()

(toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 55

change_all_jira_status() (in moduletoolium.jira), 57

change_jira_status() (in module toolium.jira),58

check() (toolium.pageelements.checkbox_page_element.Checkboxmethod), 45

check() (toolium.pageelements.input_radio_page_element.InputRadiomethod), 46

Checkbox (class in toolium.pageelements.checkbox_page_element),45

Checkboxes (class intoolium.pageelements.page_elements), 48

clear() (toolium.pageelements.input_text_page_element.InputTextmethod), 47

click() (toolium.pageelements.button_page_element.Buttonmethod), 45

close_drivers() (toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 55

CommonObject (class intoolium.pageobjects.common_object), 50

71


compare_files() (toolium.visual_test.VisualTestmethod), 64

config (toolium.driver_wrapper.DriverWrapperattribute), 53

config (toolium.pageobjects.common_object.CommonObjectattribute), 50

config_directory (toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 55

config_files (toolium.test_cases.BasicTestCase at-tribute), 58

config_log_filename(toolium.driver_wrapper.DriverWrapperattribute), 53

config_properties_filenames(toolium.driver_wrapper.DriverWrapperattribute), 53

ConfigDriver (class in toolium.config_driver), 51ConfigFiles (class in toolium.config_files), 51configure() (toolium.driver_wrapper.DriverWrapper

method), 53configure_common_directories()


configure_logger()(toolium.driver_wrapper.DriverWrappermethod), 53

configure_properties()(toolium.driver_wrapper.DriverWrappermethod), 53

configure_visual_baseline()(toolium.driver_wrapper.DriverWrappermethod), 53

configure_visual_directories()(toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 55

connect() (toolium.driver_wrapper.DriverWrappermethod), 53

connect_default_driver_wrapper()(toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 55

connect_wrapper() (in moduletoolium.behave.environment), 43

create_and_configure_wrapper() (in moduletoolium.behave.environment), 43

create_driver() (toolium.config_driver.ConfigDrivermethod), 51

crop_element() (toolium.visual_test.VisualTestmethod), 65

css_name (toolium.visual_test.VisualTest attribute), 65

Ddeepcopy() (toolium.config_parser.ExtendedConfigParser

method), 52

discard_logcat_logs() (toolium.utils.Utilsmethod), 60

download_remote_video() (toolium.utils.Utilsmethod), 60

download_videos()(toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 56

driver (toolium.driver_wrapper.DriverWrapperattribute), 53

driver (toolium.pageobjects.common_object.CommonObjectattribute), 50

driver (toolium.test_cases.AppiumTestCase attribute),58

driver (toolium.test_cases.SeleniumTestCase at-tribute), 59

driver_wrapper (toolium.pageelements.group_page_element.Groupattribute), 46

driver_wrapper (toolium.pageelements.page_element.PageElementattribute), 44

driver_wrapper (toolium.pageelements.page_elements.PageElementsattribute), 48

driver_wrapper (toolium.pageobjects.common_object.CommonObjectattribute), 50

driver_wrapper (toolium.pageobjects.page_object.PageObjectattribute), 49

driver_wrapper (toolium.test_cases.BasicTestCaseattribute), 58

driver_wrapper (toolium.visual_test.VisualTest at-tribute), 65

driver_wrappers (toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 56

DriverWrapper (class in toolium.driver_wrapper), 52DriverWrappersPool (class in

toolium.driver_wrappers_pool), 55

Eexclude_elements()

(toolium.visual_test.VisualTest method),65

ExtendedConfigParser (class intoolium.config_parser), 52

Fforce (toolium.visual_test.VisualTest attribute), 65

Gget_attribute() (toolium.pageelements.page_element.PageElement

method), 44get_center() (toolium.utils.Utils method), 60get_config_from_file()

(toolium.config_parser.ExtendedConfigParserstatic method), 52

72 Index


get_config_window_bounds()(toolium.driver_wrapper.DriverWrappermethod), 53

get_configured_value()(toolium.driver_wrappers_pool.DriverWrappersPoolstatic method), 56

get_default_config_directory()(toolium.driver_wrappers_pool.DriverWrappersPoolstatic method), 56

get_default_wrapper()(toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 56

get_driver_platform()(toolium.driver_wrapper.DriverWrappermethod), 53

get_element_box() (toolium.visual_test.VisualTestmethod), 65

get_error_message() (in module toolium.jira), 58get_error_message_from_exception() (in

module toolium.config_driver), 51get_explicitly_wait() (toolium.utils.Utils

method), 60get_first_webview_context()

(toolium.utils.Utils method), 60get_implicitly_wait() (toolium.utils.Utils

method), 60get_jira_key_from_scenario() (in module

toolium.behave.environment), 43get_method_name()

(toolium.test_cases.BasicTestCase method), 58get_native_coords() (toolium.utils.Utils method),

60get_optional() (toolium.config_parser.ExtendedConfigParser

method), 52get_remote_node() (toolium.utils.Utils method), 60get_safari_navigation_bar_height()

(toolium.utils.Utils method), 61get_scrolls_size()

(toolium.visual_test.VisualTest method),65

get_server_url() (toolium.utils.Utils method), 61get_subclass_name()

(toolium.test_cases.BasicTestCase classmethod), 58

get_subclassmethod_name()(toolium.test_cases.BasicTestCase method), 59

get_web_element() (toolium.utils.Utils method), 61get_window_size() (toolium.utils.Utils method), 61getboolean_optional()

(toolium.config_parser.ExtendedConfigParsermethod), 52

Group (class in toolium.pageelements.group_page_element),46

Groups (class in toolium.pageelements.page_elements),

48

Hhref (toolium.pageelements.link_page_element.Link at-

tribute), 47

Iinit_page_elements()

(toolium.pageobjects.page_object.PageObjectmethod), 49

initialize_config_files()(toolium.driver_wrappers_pool.DriverWrappersPoolstatic method), 56

InputRadio (class intoolium.pageelements.input_radio_page_element),46

InputRadios (class intoolium.pageelements.page_elements), 48

InputText (class intoolium.pageelements.input_text_page_element),47

InputTexts (class intoolium.pageelements.page_elements), 48

install_pytest_asserts() (in moduletoolium.behave.environment), 43

is_android_test()(toolium.driver_wrapper.DriverWrappermethod), 53

is_android_web_test()(toolium.driver_wrapper.DriverWrappermethod), 54

is_empty() (toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 56

is_ios_test() (toolium.driver_wrapper.DriverWrappermethod), 54

is_ios_web_test()(toolium.driver_wrapper.DriverWrappermethod), 54

is_maximizable() (toolium.driver_wrapper.DriverWrappermethod), 54

is_mobile_test() (toolium.driver_wrapper.DriverWrappermethod), 54

is_present() (toolium.pageelements.page_element.PageElementmethod), 44

is_remote_video_enabled() (toolium.utils.Utilsmethod), 61

is_selected() (toolium.pageelements.checkbox_page_element.Checkboxmethod), 45

is_selected() (toolium.pageelements.input_radio_page_element.InputRadiomethod), 46

is_visible() (toolium.pageelements.page_element.PageElementmethod), 44

is_web_test() (toolium.driver_wrapper.DriverWrappermethod), 54

Index 73


Jjavascript_name (toolium.visual_test.VisualTest at-

tribute), 65jira() (in module toolium.jira), 58

LLink (class in toolium.pageelements.link_page_element),

47Links (class in toolium.pageelements.page_elements),

48locator (toolium.pageelements.group_page_element.Group

attribute), 46locator (toolium.pageelements.page_element.PageElement

attribute), 44locator (toolium.pageelements.page_elements.PageElements

attribute), 48logger (toolium.driver_wrapper.DriverWrapper

attribute), 54logger (toolium.pageelements.group_page_element.Group

attribute), 46logger (toolium.pageobjects.common_object.CommonObject

attribute), 50logs_directory (toolium.driver_wrappers_pool.DriverWrappersPool

attribute), 56

Mmobile_resize() (toolium.visual_test.VisualTest

method), 65MobilePageObject (class in

toolium.pageobjects.mobile_page_object),50

Ooption (toolium.pageelements.select_page_element.Select

attribute), 47optionxform() (toolium.config_parser.ExtendedConfigParser

method), 52order (toolium.pageelements.group_page_element.Group

attribute), 46order (toolium.pageelements.page_element.PageElement

attribute), 44order (toolium.pageelements.page_elements.PageElements

attribute), 48output_directory (toolium.driver_wrappers_pool.DriverWrappersPool

attribute), 56output_log_filename

(toolium.driver_wrapper.DriverWrapperattribute), 54

Ppage_element_class

(toolium.pageelements.page_elements.Buttonsattribute), 48

page_element_class(toolium.pageelements.page_elements.Checkboxesattribute), 48

page_element_class(toolium.pageelements.page_elements.Groupsattribute), 48

page_element_class(toolium.pageelements.page_elements.InputRadiosattribute), 48

page_element_class(toolium.pageelements.page_elements.InputTextsattribute), 48

page_element_class(toolium.pageelements.page_elements.Linksattribute), 48

page_element_class(toolium.pageelements.page_elements.PageElementsattribute), 49

page_element_class(toolium.pageelements.page_elements.Selectsattribute), 49

page_element_class(toolium.pageelements.page_elements.Textsattribute), 49

page_elements (toolium.pageelements.page_elements.PageElementsattribute), 49

PageElement (class intoolium.pageelements.page_element), 43

PageElements (class intoolium.pageelements.page_elements), 48

PageObject (class intoolium.pageobjects.page_object), 49

parent (toolium.pageelements.group_page_element.Groupattribute), 46

parent (toolium.pageelements.page_element.PageElementattribute), 44

parent (toolium.pageelements.page_elements.PageElementsattribute), 49

Rremote_node (toolium.driver_wrapper.DriverWrapper

attribute), 54remote_node_video_enabled


remove_drivers() (toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 56

remove_scrolls() (toolium.visual_test.VisualTestmethod), 65

report_name (toolium.visual_test.VisualTest at-tribute), 65

reset_object() (toolium.pageelements.group_page_element.Groupmethod), 46

74 Index


reset_object() (toolium.pageelements.page_element.PageElementmethod), 44

reset_object() (toolium.pageelements.page_elements.PageElementsmethod), 49

reset_object() (toolium.pageobjects.common_object.CommonObjectmethod), 50

reset_object() (toolium.pageobjects.page_object.PageObjectmethod), 50

results (toolium.visual_test.VisualTest attribute), 65

Ssave_all_ggr_logs()


save_all_webdriver_logs()(toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 57

save_jira_conf() (in module toolium.jira), 58save_webdriver_logs() (toolium.utils.Utils

method), 61save_webdriver_logs_by_type()

(toolium.utils.Utils method), 61screenshots_directory

(toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 57

screenshots_number(toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 57

scroll_element_into_view()(toolium.pageelements.page_element.PageElementmethod), 44

Select (class in toolium.pageelements.select_page_element),47

Selects (class in toolium.pageelements.page_elements),49

selenium_select (toolium.pageelements.select_page_element.Selectattribute), 47

SeleniumTestCase (class in toolium.test_cases), 59server_type (toolium.driver_wrapper.DriverWrapper

attribute), 54session_id (toolium.driver_wrapper.DriverWrapper

attribute), 54set_config_directory()

(toolium.config_files.ConfigFiles method),51

set_config_log_filename()(toolium.config_files.ConfigFiles method),51

set_config_properties_filenames()(toolium.config_files.ConfigFiles method),51

set_implicitly_wait() (toolium.utils.Utilsmethod), 61

set_output_directory()

(toolium.config_files.ConfigFiles method),51

set_output_log_filename()(toolium.config_files.ConfigFiles method),51

set_visual_baseline_directory()(toolium.config_files.ConfigFiles method),51

setUp() (toolium.test_cases.AppiumTestCase method),58

setUp() (toolium.test_cases.BasicTestCase method),59

setUp() (toolium.test_cases.SeleniumTestCasemethod), 59

shadowroot (toolium.pageelements.group_page_element.Groupattribute), 46

shadowroot (toolium.pageelements.page_element.PageElementattribute), 44

shadowroot (toolium.pageelements.page_elements.PageElementsattribute), 49

should_reuse_driver()(toolium.driver_wrapper.DriverWrappermethod), 54

start_driver() (in moduletoolium.behave.environment), 43

stop_drivers() (toolium.driver_wrappers_pool.DriverWrappersPoolclass method), 57

swipe() (toolium.utils.Utils method), 61switch_to_first_webview_context()

(toolium.utils.Utils method), 61

TtearDown() (toolium.test_cases.BasicTestCase

method), 59tearDown() (toolium.test_cases.SeleniumTestCase

method), 59tearDownClass() (toolium.test_cases.BasicTestCase

class method), 59tearDownClass() (toolium.test_cases.SeleniumTestCase

class method), 60template_name (toolium.visual_test.VisualTest

attribute), 65Text (class in toolium.pageelements.text_page_element),

47text (toolium.pageelements.button_page_element.Button

attribute), 45text (toolium.pageelements.checkbox_page_element.Checkbox

attribute), 45text (toolium.pageelements.input_radio_page_element.InputRadio

attribute), 46text (toolium.pageelements.input_text_page_element.InputText

attribute), 47text (toolium.pageelements.text_page_element.Text at-

tribute), 47

Index 75


Texts (class in toolium.pageelements.page_elements),49

toolium.behave.environment (module), 41toolium.config_driver (module), 51toolium.config_files (module), 51toolium.config_parser (module), 52toolium.driver_wrapper (module), 52toolium.driver_wrappers_pool (module), 55toolium.jira (module), 57toolium.pageelements.button_page_element

(module), 45toolium.pageelements.checkbox_page_element

(module), 45toolium.pageelements.group_page_element

(module), 46toolium.pageelements.input_radio_page_element

(module), 46toolium.pageelements.input_text_page_element

(module), 47toolium.pageelements.link_page_element

(module), 47toolium.pageelements.page_element (mod-

ule), 43toolium.pageelements.page_elements (mod-

ule), 48toolium.pageelements.select_page_element

(module), 47toolium.pageelements.text_page_element

(module), 47toolium.pageobjects.common_object (mod-

ule), 50toolium.pageobjects.mobile_page_object

(module), 50toolium.pageobjects.page_object (module),

49toolium.test_cases (module), 58toolium.utils (module), 60toolium.visual_test (module), 64

Uuncheck() (toolium.pageelements.checkbox_page_element.Checkbox

method), 45update_magic_config_names()

(toolium.driver_wrapper.DriverWrappermethod), 54

update_properties()(toolium.config_parser.ExtendedConfigParsermethod), 52

update_visual_baseline()(toolium.driver_wrapper.DriverWrappermethod), 55

Utils (class in toolium.utils), 60utils (toolium.driver_wrapper.DriverWrapper at-

tribute), 55

utils (toolium.pageobjects.common_object.CommonObjectattribute), 50

utils (toolium.test_cases.SeleniumTestCase attribute),60

Vvideos_directory (toolium.driver_wrappers_pool.DriverWrappersPool

attribute), 57videos_number (toolium.driver_wrappers_pool.DriverWrappersPool

attribute), 57visual_baseline_directory


visual_baseline_directory(toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 57

visual_number (toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 57

visual_output_directory(toolium.driver_wrappers_pool.DriverWrappersPoolattribute), 57

VisualTest (class in toolium.visual_test), 64

Wwait (toolium.pageelements.group_page_element.Group

attribute), 46wait (toolium.pageelements.page_element.PageElement

attribute), 44wait (toolium.pageobjects.page_object.PageObject at-

tribute), 50wait_until_clickable()

(toolium.pageelements.page_element.PageElementmethod), 44

wait_until_element_attribute_is()(toolium.utils.Utils method), 62

wait_until_element_clickable()(toolium.utils.Utils method), 62

wait_until_element_contains_text()(toolium.utils.Utils method), 62

wait_until_element_not_contain_text()(toolium.utils.Utils method), 62

wait_until_element_not_visible()(toolium.utils.Utils method), 63

wait_until_element_present()(toolium.utils.Utils method), 63

wait_until_element_stops()(toolium.utils.Utils method), 63

wait_until_element_visible()(toolium.utils.Utils method), 63

wait_until_first_element_is_found()(toolium.utils.Utils method), 64

wait_until_loaded()(toolium.pageobjects.page_object.PageObjectmethod), 50

76 Index


wait_until_not_visible()(toolium.pageelements.page_element.PageElementmethod), 44

wait_until_visible()(toolium.pageelements.page_element.PageElementmethod), 44

web_element (toolium.pageelements.page_element.PageElementattribute), 45

web_elements (toolium.pageelements.page_elements.PageElementsattribute), 49

Index 77

Documents

Toolium Documentation · Toolium is a Python wrapper tool of Selenium and Appium libraries to test web and mobile applications in a single project. It provides a way of choosing and