| Library version: | 5.6.0 |
|---|---|
| Library scope: | GLOBAL |
EyesLibrary is a visual verification library for Robot Framework that uses Applitools Eyes SDK Python and SeleniumLibrary / AppiumLibrary.
To run tests, you need to have the Applitools API key. If you have an Applitools account, you could fetch it from dashboard, or you could create the free account. You may want to read Applitools documentation to understand better how Eyes works.
EyesLibrary stores configuration file inside applitools.yaml config file. Detailed info you can find in configuration docs
The general options provide defaults for all run types. The other sections are for specific types of run and define their own configuration values. By default, they inherit the general options, but they can override any configuration if necessary.
Before running tests, you must initialize applitools.yaml configuration script in root of test suite:
| python -m EyesLibrary init-config |
Check correctness of configuration file you could with command:
| python -m EyesLibrary lint-config applitools.yaml |
Add your API KEY applitools.yaml or in APPLITOOLS_API_KEY env variable and import EyesLibrary into your Robot test suite:
| Library | EyesLibrary | runner=web | config=path/to/applitools.yaml |
When writing the tests, the following structure must be adopted:
1. Eyes Open
A browser or application must be running when opening the session. To open a browser/application, consult the documentation for SeleniumLibrary and/or AppiumLibrary.
Afterwards, the session may be opened. See Eyes Open.
2. Visual Checks
Between opening and closing the session, you can run your visual checks.
See Eyes Check Window, Eyes Check Region By Element, Eyes Check Region By Selector, Eyes Check Region By Coordinates, Eyes Check Frame By Element, Eyes Check Frame By Name, Eyes Check Frame By Index and Eyes Check Frame By Selector.
You can also verify if there's an open session with Is Eyes Open.
3. Eyes Close Async
See Eyes Close Async.
Initialize the EyesLibrary
| Arguments | Description |
|---|---|
| runner | Specify one of web, web_ufg, or mobile_native runners (by default web) |
| config | Path to applitools.yaml (if no specify, trying to find it in test suite dir) |
| run_on_failure | Specify keyword to run in case of failure (By default Eyes Abort Async) |
Returns a CheckSettings object with accessibility region specified in the arguments.
| Arguments | Description |
|---|---|
| Region | Mandatory - The accessibility region e.g. [100 200 300 300] |
| Type | Mandatory - Type of AccessibilityRegion. (IgnoreContrast, RegularText, LargeText, BoldText, GraphicalObject) |
Example:
| Eyes Check | ||
| ... Accessibility Region By Coordinates | [10 20 30 40] | GraphicalObject |
Returns a CheckSettings object with accessibility region specified in the arguments.
| Arguments | Description |
|---|---|
| Element | Mandatory - The accessibility region e.g. [100 200 300 300] |
| Type | Mandatory - Type of AccessibilityRegion. (IgnoreContrast, RegularText, LargeText, BoldText, GraphicalObject) |
Example:
| Eyes Check | ||
| ... Accessibility Region By Coordinates | ${element} | GraphicalObject |
Returns a CheckSettings object with accessibility region specified in the arguments.
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector for element for accessibility region. Selenium/Appium formats are supported. |
| Type | Mandatory - Type of AccessibilityRegion. (IgnoreContrast, RegularText, LargeText, BoldText, GraphicalObject) |
Example:
| Eyes Check | ||
| ... Accessibility Region By Selector | //selector | GraphicalObject |
Returns a CheckSettings object with content region specified in the argument.
| Arguments | Description |
|---|---|
| Region | Mandatory - The content region in format [left top width height] ,e.g. [100 200 300 300] |
Example:
| Content Region By Coordinates | [10 20 100 100] |
Returns a CheckSettings object with content region specified in the argument.
| Arguments | Description |
|---|---|
| Element | Mandatory - The element to become content region |
Example:
| ${element}= | Get Webelement | //*[@id="logo"] |
| ${target}= | Content Region By Element | ${element} |
Returns a CheckSettings object with content region specified in the argument.
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector for element for content region. Selenium/Appium formats are supported. |
Example:
| Content Region By Selector | css:div |
Returns a BatchInfo ID string that may be used as batch argument on Eyes Open.
| Arguments | Description |
|---|---|
| Name | The name of the batch |
| Started At | The date and time that will be displayed in the Test Manager as the batch start time (*) |
| Batch ID | This argument groups together tests ran in different executions |
The Started At argument may be passed as:
Example:
| ${batch_id}= | Create Eyes Batch |
Returns a CheckSettings object with disable_browser_fetching specified in the arguments.
Example:
| Eyes Check | |
| ... Disable Browser Fetching |
Returns a CheckSettings object with enabled layout_breakpoints specified in the arguments.
Example:
| Eyes Check | |
| ... Enable Layout Breakpoints |
Returns a CheckSettings object specified enable patterns.
Example:
| Eyes Check | Target Window | Enable Patterns |
Stops execution without calling close(). This method does all the cleanup normally done by close. If this method is called, and close has not been called, then the test will have a status of Aborted in the Test Manager.
Example:
| Eyes Abort Async |
Check with target
| Arguments | Description |
|---|---|
| Target Keyword | Mandatory - Target Keyword that market with Target Keyword tag |
Example:
| Eyes Check | Target Window | |
| Eyes Check | Target Region By Coordinates | [34 56 78 89] |
Check specified frame by element
| Arguments | Description |
|---|---|
| Element | Mandatory - The frame to check |
Example:
| Eyes Check Frame By Element | ${element} |
Check specified frame by index
| Arguments | Description |
|---|---|
| Frame Index | Mandatory - Index of the frame to check. |
Example:
| Eyes Check Frame By Index | 2 |
Check specified frame by name
| Arguments | Description |
|---|---|
| Frame Name | Mandatory - Name of the frame to check. |
Example:
| Eyes Check Frame By Name | frameName |
Check specified frame by name
| Arguments | Description |
|---|---|
| Selector | Mandatory - Selector of the frame to check. |
Example:
| Eyes Check Frame By Selector | css:#selector |
Check specified region
| Arguments | Description |
|---|---|
| Region | Mandatory - The region to check in format [left top width height] ,e.g. [100 200 300 300] |
Example:
| Eyes Check Region By Coordinates | [40 50 200 448] |
Check specified region by element
| Arguments | Description |
|---|---|
| Element | Mandatory - The element to check |
Example:
| Eyes Check Region By Element | ${element} |
Check specified region by selector
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector to check. |
Example:
| Eyes Check Region By Element | css:#selector |
Check current browser window
Example:
| Eyes Check Window |
Closes a session and returns the results of the session. If a test is running, aborts it. Otherwise, does nothing.
| Arguments | Description |
|---|---|
| Raise Exception (bool) | If you don't want an exception to be thrown if there are new, missing or mismatched steps, pass 'False' in the variable |
Example:
| Eyes Close Async | ${false} |
Shared parameters section from applitools.yaml could be overwritten during Eyes Open call, see Preconditions.
| Arguments | Description |
|---|---|
| Test Name | By default fetched from name of current test. Could be overfritet here. |
| Viewport Size | The viewport size of the browser window in format [width height] e.g. [1900 1080] |
| App Name | The name of the application under test |
| Host OS | The operating system of the test, can be used to override the OS name to allow cross OS verification |
| Host App | The browser name for the test, can be used to override the browser name to allow cross browser verification |
| Match Level | The match level for the comparison of this test's checkpoints - can be STRICT, LAYOUT, CONTENT or EXACT |
| Baseline Env Name | Name of the branch where the baseline reference will be taken from and where new and accepted steps will be saved to |
| Batch | Accepts desired batch returned by Create Batch Info or batch name |
| Branch Name | The branch to use to check test |
| Parent Branch Name | Parent Branch to base the new Branch on |
| Force Full Page Screenshot | Will force the browser to take a screenshot of whole page |
| Stitch Mode | Type of stitching used for full page screenshots - can be CSS or SCROLL |
| Match Timeout | Determines how much time in milliseconds Eyes continues to retry the matching before declaring a mismatch on this test checkpoints |
| Hide Scrollbars | Sets if the scrollbars are hidden this session's tests, by passing 'True' or 'False' in the variable |
| Save New Tests | Sets if the new checkpoints on this session are automatically accepted, by passing 'True' or 'False' in the variable |
| Wait Before Screenshots | Determines the number of milliseconds that Eyes will wait before capturing a screenshot on this test checkpoints |
| Send DOM | Sets if DOM information should be sent for this session's checkpoints |
| Is Disabled | Determines whether or not interactions with Eyes will be silently ignored for this test |
Example:
| Eyes Open | TestName | [1024 768] | AppNameOverride | OSOverride | HostAppOverride | batchname=Some batch name |
Returns a CheckSettings object with floating region specified in the arguments.
| Arguments | Description |
|---|---|
| Region | Mandatory - The floating region e.g. [100 200 300 300] |
| Max Up Offset | The maximum amount that the region can shift upwards and still be considered matching. |
| Max Down Offset | The maximum amount that the region can shift downwards and still be considered matching. |
| Max Left Offset | The maximum amount that the region can shift to the left and still be considered matching. |
| Max Right Offset | The maximum amount that the region can shift to the right and still be considered matching. |
Example:
| Eyes Check Window | |||||
| ... Floating Region By Coordinates | [10 20 100 100] | 5 | 5 | 5 | 5 |
| ... Floating Region By Coordinates | [10 20 100 100] | max_right_offset=5 |
Returns a CheckSettings object with floating region specified in the arguments.
| Arguments | Description |
|---|---|
| Element | Mandatory - The WebElement to set as float region. |
| Max Up Offset | The maximum amount that the region can shift upwards and still be considered matching. |
| Max Down Offset | The maximum amount that the region can shift downwards and still be considered matching. |
| Max Left Offset | The maximum amount that the region can shift to the left and still be considered matching. |
| Max Right Offset | The maximum amount that the region can shift to the right and still be considered matching. |
Example:
| ${element}= | Get Webelement | //*[@id="logo"] | |||
| Eyes Check Window | |||||
| ... Floating Region By Element | ${element} | 5 | 5 | 5 | 5 |
| ... Floating Region By Element | ${element} | max_left_offset=5 |
Returns a CheckSettings object with floating region specified in the arguments.
| Arguments | Description |
|---|---|
| Selector | The selector to become floating region e.g. //*[@id="logo"] |
| Max Up Offset | The maximum amount that the region can shift upwards and still be considered matching. |
| Max Down Offset | The maximum amount that the region can shift downwards and still be considered matching. |
| Max Left Offset | The maximum amount that the region can shift to the left and still be considered matching. |
| Max Right Offset | The maximum amount that the region can shift to the right and still be considered matching. |
Example:
| Eyes Check Window | |||||
| ... Floating Region By Selector | //*[@id="logo"] | 5 | 5 | 5 | 5 |
| ... Floating Region By Selector | //*[@id="logo"] | max_left_offset=5 |
Returns a CheckSettings object with floating region specified in the arguments.
| Arguments | Description |
|---|---|
| Max Offset | Mandatory - The maximum amount that the region can shift in any direction and still be considered matching. |
| Region | Mandatory - The floating region e.g. [100 200 300 300] |
Example:
| Eyes Check | ||
| ... Floating Region With Max Offset By Coordinates | 5 | [10 20 100 100] |
Returns a CheckSettings object with floating region specified in the arguments.
| Arguments | Description |
|---|---|
| Max Offset | Mandatory - The maximum amount that the region can shift in any direction and still be considered matching. |
Element | Mandatory - The element to become floating region
Example:
| ${element}= | Get Webelement | //*[@id="logo"] | |
| Eyes Check | |||
| ... Floating Region With Max Offset By Element | 5 | ${element} |
Returns a CheckSettings object with floating region specified in the arguments.
| Arguments | Description |
|---|---|
| Max Offset | Mandatory - The maximum amount that the region can shift in any direction and still be considered matching. |
| Selector | Mandatory - The selector to become floating region e.g. //*[@id="logo"] |
Example:
| Eyes Check | ||
| ... Floating Region With Max Offset By Selector | 5 | //*[@id="logo"] |
Returns a CheckSettings object specified fully.
Example:
| Eyes Check | Target Window | Fully |
Returns a CheckSettings object specified ignore caret.
Example:
| Eyes Check | Target Window | Ignore Caret |
Returns a CheckSettings object specified ignore displacements.
Example:
| Eyes Check | Target Window | Ignore Displacements |
Returns a CheckSettings object that ignores the region specified in the argument.
| Arguments | Description |
|---|---|
| Region | Mandatory - The region to ignore in format [left top width height] ,e.g. [100 200 300 300] |
Example:
| Ignore Region By Coordinates | [10 20 100 100] |
Returns a CheckSettings object that ignores the region specified in the argument.
| Arguments | Description |
|---|---|
| Element | Mandatory - The element to ignore |
Example:
| ${element}= | Get Webelement | //*[@id="logo"] |
| ${target}= | Ignore Region By Element | ${element} |
Returns a CheckSettings object that ignores the region specified in the argument.
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector for element to ignore. Selenium/Appium formats are supported. |
Example:
| Ignore Region By Selector | css:div |
Returns True if Eyes is opened
Example:
| ${is_open}= | Is Eyes Open |
Returns a CheckSettings object specified layout_breakpoints in the arguments.
| Arguments | Description |
|---|---|
| breakpoints | Specify layout breakpoint, e.g. 25 56 89 |
Example:
| Eyes Check | Target Window | Layout Breakpoints | 23 45 67 89 |
Returns a CheckSettings object with layout region specified in the argument.
| Arguments | Description |
|---|---|
| Region | Mandatory - The layout region in format [left top width height] ,e.g. [100 200 300 300] |
Example:
| Leyout Region By Coordinates | [10 20 100 100] |
Returns a CheckSettings object with layout region specified in the argument.
| Arguments | Description |
|---|---|
| Element | Mandatory - The element with layout region e.g. [100 200 300 300] |
Example:
| ${element}= | Get Webelement | //*[@id="logo"] |
| ${target}= | Layout Region By Element | ${element} |
Returns a CheckSettings object with layout region specified in the argument.
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector for element for layout region. Selenium/Appium formats are supported. |
Example:
| Layout Region By Selector | css:div |
Returns a CheckSettings object specified match level.
| Arguments | Description |
|---|---|
| match_level | Specify the match level that should be used for the target area (NONE LAYOUT CONTENT STRICT EXACT) |
Example:
| Eyes Check | Target Window | Match Level STRICT |
Returns a CheckSettings object with selected Scroll Root Element
| Arguments | Description |
|---|---|
| Element | Mandatory - The scroll root element |
Example:
| Scroll Root Element By Element | ${element} |
Returns a CheckSettings object with selected Scroll Root Element by selector
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector of scroll root element |
Example:
| Scroll Root Element By Element | ${element} |
Returns a CheckSettings object specified send dom.
Example:
| Eyes Check | Target Window | Send Dom |
Returns a CheckSettings object with content region specified in the argument.
| Arguments | Description |
|---|---|
| Region | Mandatory - The strict region in format [left top width height] ,e.g. [100 200 300 300] |
Example:
| Strict Region By Coordinates | [10 20 100 100] |
Returns a CheckSettings object with strict region specified in the argument.
| Arguments | Description |
|---|---|
| Element | Mandatory - The element to become strict region |
Example:
| ${element}= | Get Webelement | //*[@id="logo"] |
| ${target}= | Strict Region By Element | ${element} |
Returns a CheckSettings object with strict region specified in the argument.
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector for element for strict region. Selenium/Appium formats are supported. |
Example:
| Eyes Check | |
| ... Strict Region By Selector | css:div |
Returns a CheckSettings object with selected Frame and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Element | Mandatory - The frame to check |
Example:
| ${target}= | Target Frame By Element | ${element} |
Returns a CheckSettings object with selected Frame and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Frame Index | Mandatory - Index of the frame to check. |
Example:
| ${target}= | Target Frame By Index | 2 |
Returns a CheckSettings object with selected Frame and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Frame Name | Mandatory - Name of the frame to check. |
Example:
| ${target}= | Target Frame By Name | frameName |
Returns a CheckSettings object with selected Frame and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Selector | Mandatory - Selector of the frame to check. |
Example:
| ${target}= | Target Frame By Selector | css:#selector |
Returns a CheckSettings object with selected Region and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Region | Mandatory - The region to check in format [left top width height] ,e.g. [100 200 300 300] |
Example:
| ${target}= | Target Region By Coordinates | [10 30 40 50] |
Returns a CheckSettings object with selected Region and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Element | Mandatory - The element to check |
Example:
| ${target}= | Target Region By Element | ${element} |
Returns a CheckSettings object with selected Region and any number of Check Settings Keywords.
| Arguments | Description |
|---|---|
| Selector | Mandatory - The selector to check. |
Example:
| ${target}= | Target Frame By Selector | css:#selector |
Returns a CheckSettings object with Window selected and any number of Check Settings Keywords.
Example:
| ${target}= | Target Window |
Returns a CheckSettings object specified maximum amount of time that Eyes should retry capturing the window content if there are mismatches.
| Arguments | Description |
|---|---|
| timeout | Specify timeout in milliseconds, e.g. 1000 (1 sec) |
Example:
| Eyes Check | Target Window |
| ... Timeout | 3000 |
Returns a CheckSettings object specified use dom.
Example:
| Eyes Check | Target Window | Use Dom |
Returns a CheckSettings object specified variant group id.
| Arguments | Description |
|---|---|
| variation_group_id | will be associated with all of the test result steps that result from executing this checkpoint |
Example:
| Eyes Check | Target Window | Variation Group Id | variation1 |
Returns a CheckSettings object with VisualGridOption specified in the arguments.
| Arguments | Description | ||
|---|---|---|---|
| name | Mandatory - The VisualGridOption name. | ||
| value | Mandatory - The VisualGridOption value. |
Example:
| Eyes Check | |
| ... Visual Grid Option | key name value |
| ... Visual Grid Option | key name2 value |
Returns a CheckSettings object specified tag from argument.
| Arguments | Description |
|---|---|
| name | Specifies a tag for this target (instead of a parameter to the Eyes Check ) |
Example:
| Eyes Check | Target Window |
| ... With Name | User Check Step name |