Selenium - Java

     This page covers the following topics:

Installing Applitools SDK for Selenium Java


Applitools Eyes SDK for Selenium Java can be downloaded from Maven (the name of the package is eyes-selenium-java).

To install the SDK, add the following to your pom.xml file (make sure to change the version number below to the latest version that is available on Maven):

<dependency>
 <groupId>com.applitools</groupId>
 <artifactId>eyes-selenium-java</artifactId>
 <version>RELEASE</version>
</dependency>


Eyes Object

Eyes object is the main object in Applitools Eyes SDK.

Eyes Creation


 Eyes eyes = new Eyes();

API Key

Before anything else, you should set the API key which allows you work with the Eyes server. Note that you use a static function for that, so it will be available to all of your objects. In order to obtain your API Key, login to Applitools Eyes web application and open your account details page.

 eyes.setApiKey("MY_API_KEY");

Replace MY_API_KEY with the API key of your account (you can find it in your signup email).

(Optional) Set viewport size

An alternative option for setting the size of the viewport

 eyes.setViewportSize(driver, new RectangleSize(width, height));


Initialization

The open method returns a custom web driver object that monitors all the driver actions. From this point, the new custom driver object should be used for all the actions in the test.

 driver = eyes.open(driver, appName, testName, viewportSize);

driver – the relevant Selenium Webdriver object.

appName – string that represents the logical name of the AUT (this name will be presented in the test result)

testName – string that represents the name of the test (this name will be presented in the test result

viewportSize – a predefined viewport size that will be used for the browser window during this test (this parameter is very important for visual tests to ensure that the test will run of a defined viewport size and the results will be consistent)


Match Timeout

MatchTimeout defines the default amount of time (in miliseconds) that Eyes will wait for an image to stabilize to a point that it is similar to the baseline image (the default value is 2 seconds). Click here for further explanation.

eyes.setMatchTimeout(TimeOut);

Visual Validation Checkpoints


The check window command will take a snapshot of the current window in the AUT and will perform smart visual comparison of that window with the baseline. In case this is a new window that does not exist in the baseline, this window will be added to the baseline.

 eyes.checkWindow();
 eyes.checkWindow(windowName);
 eyes.checkWindow(matchTimeout, windowName);
windowName – String that represents the logical name of this window/validation point that will appear in the test result report, the default value is "null"

matchTimeout - MatchTimeout in seconds, given for the step to pass.


Visual validation checkpoint of a specific region

Check region method works in a similar way to check window, except for the fact that it takes a screenshot of the HTML element specified as its input (by means of a WebDriver "By" selector) instead of a screenshot of the entire web page. The check region command will take a snapshot of the specific object, regardless of where it appears in the page, and will perform smart visual comparison of that region with the baseline. In case this is a new region that does not exist in the baseline, this region will be added as a new region to the baseline.


eyes.checkRegion(selector);
eyes.checkRegion(selector, stitchContent);
eyes.checkRegion(selector, matchTimeout, tag);
eyes.checkRegion(selector, matchTimeout, tag, stitchContent);
eyes.checkRegion(selector, tag);
eyes.checkRegion(selector, tag, stitchContent);
eyes.checkRegion(region);
eyes.checkRegion(region, matchTimeout, tag);
eyes.checkRegion(element);
eyes.checkRegion(element, stitchContent);
eyes.checkRegion(element, matchTimeout, tag);
eyes.checkRegion(element, matchTimeout, tag, stitchContent);
eyes.checkRegion(element, tag);
eyes.checkRegion(element, tag, stitchContent);

selector – the “By” selector (for Selenium Webdriver) that identifies the web-element. 

stitchContent - By enabling this parameter to true - Eyes will scroll down the web-element takes screenshots of the element and and stitch them into one image, the default value is false.

tag – a string that represents the logical name of this validation point that will appear in the test result report.

matchTimeout -  MatchTimeout in milliseconds, given for the step to pass.

region - Describe a region in the web-site, Read more about it here.

element - The desired selenium web element.

Region

This element describes a specific area in the web-site.

Region region = new Region(left,top,width,height);
Region region = new Region(location, size);


left - Integer, describing the X coordinate (by pixels) of the top left corner of the region.

top - Integer, describing the y coordinate (by pixels) of the top left corner of the region.
width - Integer, describing the width (by pixels) of the region.
height - Integer, describing the height (by pixels) of the region.
location - a Location, a pair of integers describing x,y coordinate.
size - a Rectangle, a pair of integers describing width height of area on the screen.

Visual validation checkpoint of iFrames in page

Iframes are usually scrollable and not displayed fully on the page, it is possible to focus validation only on a specified iframe so the SDK will scroll and stitch all the parts of the frame into a single picture and thus only one validation step.

eyes.checkFrame(frameIndex);
eyes.checkFrame(frameIndex, matchTimeout, tag);
eyes.checkFrame(frameIndex, tag);
eyes.checkFrame(frameNameOrId);
eyes.checkFrame(frameNameOrId, matchTimeout, tag);
eyes.checkFrame(frameNameOrId, tag);
eyes.checkFrame(framePath, matchTimeout, tag);
eyes.checkFrame(framePath, tag);
eyes.checkFrame(framePath);
eyes.checkFrame(frameReference);
eyes.checkFrame(frameReference, matchTimeout, tag);
eyes.checkFrame(frameReference, tag);

frameIndex - Integer the desired iframe index.

frameNameOrId - String the iframe element Name or ID.

framePath - An array of strings, a path (by IDs or by Name) to a nested iframe under test. 

frameReference - A webElement identifier of the iframe.

matchTimeout -  MatchTimeout in seconds, given for the step to pass.

tag – a string that represents the logical name of this validation point that will appear in the test result report.

Ending a test

At the end of each test, make sure to call the eyes.close method to notify the service that the test completed successfully. It is recommended to also call the method eyes.abortIfNotClosed at the end of the test as part of the ‘finally’ block to distinguish between completed tests and tests which were aborted abnormally (e.g. an exception was thrown).

try {
	...
    eyes.close();
}finally{
    eyes.abortIfNotClosed();
}

 In the “finally” block of Selenium tests, you would usually also want to include “driver.quit()”, since the test has either finished or failed.

(Optional) Ending tests without throwing exception on failure

The default behaviour on failure is to throw exception or raise error on test ending. To override this behaviour use the following overrides which takes a boolean.

try{
	...
    TestResults testResults = eyes.close(false);
}finally {
    eyes.abortIfNotClosed();
}

testResults - Test results details, Contains attributes about the test and the failure, such as:

URL - A String containing the URL to the report of the test in Applitools dashboard.

Steps - An integer representing the total steps count.

Matches - An integer representing the total matches count.

Mismatches - An integer representing the total mismatches count.

Missing - An integer representing How many missing steps found.

ExactMatches - An integer representing the amount of matches compared in exact match level.

StrictMatches - An integer representing the amount of matches compared in strict match level.

ContentMatches - An integer representing the amount of matches compared in content match level.

LayoutMatches - An integer representing the amount of matches compared in layout match level.

isNew - A Boolean value indicates whether the test classified as a new test.

(Optional) Creating a batch of tests

The object BatchInfo represent a batch/collection of tests that will be unified as one group in the Test Manager screen and the result of all tests in a batch will determine the batch result. In order to start a batch, you should create a BatchInfo object, and associate it to the Eyes object (before calling the “eyes.open”). In order to add additional tests to the same batch, make sure to call eyes.setBatch for each of the tests/Eyes objects (so every test in the batch should start with creating an Eyes object, calling eyes.setBatch, eyes.open and ending the test with eyes.close).

BatchInfo batch = new BatchInfo(batchName);
eyes.setBatch(batch);

batchName – string that represents the logical name that will be assigned to this batch.

Use the command eyes.setBatch to associate a test to the batch using the eyes instance


(Optional) Enabling Logs

Enabling Logs to Console:

The logHandler method of the Eyes object enables logging for troubleshooting purposes.


eyes.setLogHandler(new StdoutLogHandler(true));

Enabling Logs to File:

eyes.setLogHandler(new FileLogger("path/to/file.log", true, true));

(Optional) Working with branches 

Applitools Eyes include built-in support for branching, and allows creating separate baselines per branch, so whenever a developer makes changes in the app, he can run his visual tests locally without affecting other branches, and only commit the baseline changes after making sure that the tests are passing properly.

In order to create a branch, simply call the method eyes.setBranch after creating the Eyes object and before starting the test with the name of the branch as the parameter for this method. As a result, the subsequent tests will run as part of that branch and any baseline changes that you will perform on these tests from the web application will be private to this branch.


eyes.setBranchName(branchName);

branchName – the name of the branch to create.

The initial baseline used in a branch is taken from its parent branch. You can specify the parent branch by calling the setParentBranchName method with the parent branch name as a parameter. If you don't specify a parent branch, the default branch will be used. Note that just like branching code; the baseline is copied from the parent branch only the first time it is accessed. Once the baseline is accessed in a branch, it is no longer affected by changes made in the parent branch.

eyes.setParentBranchName(parentBranchName);

parentBranchName – the name of the parent branch to inherit from

(Optional) Merging Branches

Click here to learn how to automatically create a separate baseline per branch


(Optional) Overriding test comparison level

Comparison sensitivity, aka ‘match level’ is set by default to Strict to get optimal coverage. Sometimes for specific tests it is required to change the default comparison level.

eyes.setMatchLevel(MatchLevel.<Level>);

Level - The match level of the test 

  • Exact - Pixel to pixel comparison, for demonstration purposes and debugging, will fail a test if a pixel is not in place. (not lace. (not recommended)
  • Strict - strict is the default match level, it mimics human eyes so only significant visual changes will be spotted, while small changes that are not visible to a human eye will be ignored.
  • Content - ignores style and anti-aliasing differences, while spotting content changes. (the content level can be useful if your website includes different styles which are not relevant for your tests).
  • Layout - ignores content changes, and detects only layout changes. (useful for pages with dynamic content and localized pages)

Note: Overriding the match level is only effective if set before initialization.


(Optional) Automatic baseline creation (Default: True)

New tests presented to the server are automatically saved as baseline. To override this functionality so baseline creation will be applied manually by reviewing and approving the steps in applitools eyes Test Manager, set ‘SaveNewTests’ to false before test stat.

eyes.setSaveNewTests(true/false);

(Optional) Auto-save on failure (Default: False)

For maintenance and debugging purposes it is possible to make eyes to save automatically failed results as baseline by setting ‘SaveFailedTests’ property to true before test started.

* It is highly unrecommended to set this property in production since all failures will be saved automatically without distinguishment between bugs and features.

eyes.setSaveFailedTests(true/false);

(Optional) Force full page screenshot

By default when calling the ‘checkWindow’ command, only the visible area (viewport) will be taken in a screenshot. It is possible to set Eyes to ‘stitch’ together all the scrollable areas into a single screenshot to show the entire page. To set full page stitching, pass true to ‘setForceFullPageScreenshot’:

eyes.setForceFullPageScreenshot(true);

Another way of taking fullpage screenshot is using Css transition. Css scrolling and stitching is an alternative way of page scrolling usually comes to help with floating elements to stay in place when scrolling.


(Optional) Setting app environment attributes

Normally applitools eyes SDKs automatically identifies the environment that is used to run the tests and creates a separate baseline for each environment. In order to override app environment parameters, you can explicitly call to ‘setHostOS’ and 'setHostApp':

eyes.setHostOS(HostOS);

hostOs - The OS name and its version or any other os-alike identifier.

eyes.setHostApp(HostApp);

hostApp - The application name, if there is, such as browser name or any other app-alike identifier.

(Optional) Set Baseline Name

eyes.setBaselineName("baseline");


(Optional) Set Wait before Screenshots

Sets the amount of time to wait (MSec) between scrolling and stitching when using full page/stitch content

with one of the methods, checkWindow/checkRegion/checkFrame
eyes.setWaitBeforeScreenshots(TimeMS);      //Time in milliseconds

(Optional) Hide Scroll bars

This command hides the scrollbars while taking the screenshots.

eyes.setHideScrollbars(true);

(Optional) CSS stitching


An alternative way to perform full page screenshot (scrolling and stitching) to anchor floating UI elements (ie. top menus, help widgets) in place so they won't appear on every section that been taken.
eyes.setStitchMode(StitchMode.CSS);

Region

This element describes a specific area in the web-site.

Region region = new Region(left,top,width,height);
Region region = new Region(location, size);

left - Integer, describing the X coordinate (by pixels) of the top left corner of the region.

top - Integer, describing the y coordinate (by pixels) of the top left corner of the region.
width - Integer, describing the width (by pixels) of the region.
height - Integer, describing the height (by pixels) of the region.
location - a Location, a pair of integers describing x,y coordinate.
size - a Rectangle, a pair of integers describing width height of area on the screen.

Configuring a proxy server

This section explains how to configure a proxy server in the Applitools Eyes SDK to address issues such as connection refused or connection timeout when using Applitools Eyes behind a proxy server. 

Please make sure to add the commands before calling new Eyes() and also import the below package :
import com.applitools.eyes.ProxySettings;

eyes.setProxy(new ProxySettings("http://YOUR-PROXY-URI"));

OR

eyes.setProxy(new ProxySettings("http://YOUR-PROXY-URI", YOUR_USER, YOUR_PASSWORD));