# Selenium Java Tutorial

Welcome! Applitools is a thin layer on top of Selenium that provides advanced A.I. capabilities to simplify your tests. This tutorial has a "Quick start" and a detailed "Step-by-Step guide" to help you get started with Applitools.

# Quick Start 🚀

# 1. Import the SDK into Maven's pom.xml

<!-- This is the Applitools Selenium Java SDK -->
	<!-- Use JDK 1.8 (required for Maven CLI) -->
	<properties>
		<maven.compiler.source>1.8</maven.compiler.source>
		<maven.compiler.target>1.8</maven.compiler.target>
	</properties>

	<dependencies>
		<!-- This is the Applitools Selenium Java SDK -->
		<dependency>
			<groupId>com.applitools</groupId>
			<artifactId>eyes-selenium-java3</artifactId>
			<version>RELEASE</version>
		</dependency>

		<!-- Required to run "mvn package" which runs test -->
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>4.12</version>
			<scope>test</scope>
		</dependency>

		<!-- Required for Java 10 -->
		<dependency>
			<groupId>javax.activation</groupId>
			<artifactId>activation</artifactId>
			<version>1.1.1</version>
		</dependency>

	</dependencies>

# 2. Initialize the SDK and set the API key

// Initialize the eyes SDK and set your private API key.
Eyes eyes = new Eyes();

// Set Applitools API key
eyes.setApiKey("APPLITOOLS_API_KEY");

# 3. Set the application (AUT) name, the test name and set the browser's viewport size

// Start the test by setting AUT's name, window or the page name that's being tested, viewport width and height
eyes.open(driver, "appName","windowName", new RectangleSize(600, 800));

// Navigate the browser to the "ACME" demo app
driver.get("https://demo.applitools.com");

# 4. Generate screenshot.

The following uploads the image data to Applitools for the AI to compare differences, generate baseline and so on.

// Visual checkpoint.
eyes.checkWindow("Login window"));

# 5. End the test

// End the test
eyes.close();

// Close the browser.
driver.quit();

// If the test was aborted before eyes.close was called, ends the test as aborted.
eyes.abortIfNotClosed();
     

# Putting it all together (simplified code)

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import com.applitools.eyes.selenium.Eyes;
import com.applitools.eyes.RectangleSize;

public class App {

	public static void main(String[] args) {

    //Use Chrome browser
		WebDriver driver = new ChromeDriver();

		// Initialize the eyes SDK and set your private API key.
		Eyes eyes = new Eyes();

		// Set the API key from the env variable. Please read the "Important Note"
		// section above.
		eyes.setApiKey("APPLITOOLS_API_KEY");

		try {


			// Start the test by setting AUT's name, window or the page name that's being tested, viewport width and height
			eyes.open(driver, "appName","windowName", new RectangleSize(600, 800));

			// Navigate the browser to the "ACME" demo app
			driver.get("https://demo.applitools.com");

			// Visual checkpoint #1.
			eyes.checkWindow("Login window");

      //🌟 Note: You can have multiple "checkWindow" to create multiple test steps within a test.🌟  
      //For example, you may want to test errors in the login window after clicking a login button,
      //In that case, you may add the following before you call eyes.close(). 
      //This will create a test with two test steps.
      //driver.click("login");
      //eyes.checkWindow("Login Window Error");

			// End the test.
			eyes.close();

		} catch (Exception e) {
			System.out.println(e);
		} finally {

			// Close the browser.
			driver.quit();

			// If the test was aborted before eyes.close was called, ends the test as
			// aborted.
			eyes.abortIfNotClosed();

			// End main test
			System.exit(0);
		}

	}
}

# Step-by-Step guide

The tutorial provides a detailed step-by-step guide to help you get started. This has lots of gifs and pictures to help you glide through it. Our objective is to quickly show you how powerful and useful AI can be in automation testing.

• Part 1 - 🚀 Setup Applitools and create a baseline

• Part 2 - 🐞 Find UI bugs and analyze differences using AI

• Part 3 - 🤖 Understand why Applitools AI is superior to pixel-by-pixel comparison

• Part 4 - ✅ Accepting hundreds of changes by clicking a button instead of updating numerous tests

• Part 5 - 👁 Use our advanced AI tools to work with real-world scenarios

• Part 6 - 🎉 Congratulations!!

# Part 1 - Setup environment and create a baseline

Test Overview:

In this part, you will set up the environment to run the test locally and then store a baseline image of just the login page. We will use the app page later on.

Login page:

App page:

# Step 1.1: Install Prerequisites

1. Create an Applitools account and obtain your API key from the Person Icon > "My API key" menu.

2. Please set the APPLITOOLS_API_KEY environment variable

   • Mac: export APPLITOOLS_API_KEY='YOUR_API_KEY'

   • Windows: set APPLITOOLS_API_KEY='YOUR_API_KEY'

   TIP

   1. You may skip this step if you want to hard code the API KEY inside the tutorial project's code.
   2. It's better to store APPLITOOLS_API_KEY in the system variables (in Windows) or in the ~/.bash_profile (in Mac) so that it is accessible from all Terminal shells

3. Install Java's Java SE Development Kit (JDK) from here.

• Set JDK's JAVA_HOME environment variable to so that the command line can find JDK

  • Mac:

    # Find the Java installation folder path.

    • First, find where the Java is installed on your mac.
    • Run /usr/libexec/java_home in your Terminal
    • You will see something like /Library/Java/JavaVirtualMachines/jdk-10.0.2.jdk/Contents/Home. The path will vary depending on the version of the JDK and your Mac's OS version. We need to now set this folder as JAVA_HOME environment variable.

    # Setup JAVA_HOME Environment variable

    • Open ~/.bash_profile file (Create one if it's missing using touch ~/.bash_profile).
    • Add the line export PATH="<PATH_TO_JDK_FOLDER>:$PATH".
    • Change the <PATH_TO_JDK_FOLDER> to the folder you got earlier.
    • For example: export PATH=/Library/Java/JavaVirtualMachines/jdk-10.0.2.jdk/Contents/Home:$PATH
    • Save it and close the file.
    • Run source ~/.bash_profile. This will load the environment variables from the ~/.bash_profile file.
    • Run $ echo $JAVA_HOME. It shuld say something like: /Library/Java/JavaVirtualMachines/jdk-10.0.2.jdk/Contents/Home

    # Test your JAVA_HOME setup

    • Run javac --version in your Terminal. It should show something like javac 10.0.2.
    • Run echo $JAVA_HOME and it should show the path you set earlier.

  • Windows:

    # Find the Java installation folder path

    • Typically it is something like C:\Program Files\Java\jdk10.0.2

    # Setup JAVA_HOME Environment variable

    • Navigate to Computer (Right click) | Properties | Advanced System Settings | Advanced (Tab) | Environment variables | System Variables.
    • Click on New
    • Add JAVA_HOME as the Variable Name.
    • Enter JDK installation path in the Variable Value field. Typically this looks something like: C:\Progra~1\Java\jdk10.0.2
    • Click on Save

    # Test your JAVA_HOME setup

    • Restart your command line prompt to load the new environment variable.
    • Run javac --version in your command line prompt. It should say something like javac 10.0.2.

4. Download Maven binary Zip file from here.

   • It should look something like apache-maven-3.5.4-bin.zip
   • Follow the installation instructions from here to add it to the PATH.

   TIP

   1. It's better if you add it permanently to the environment so when you open a new Terminal the values will persist. Otherwise, you may have to redo it for everytime you open the Terminal. This means you should put it in the ~/.bash_profile file (Mac) or in System variables in Windows. For more, see the Steps for adding Chromedriver to the PATH below.
   2. The Maven executable is inside /bin folder of the extracted Maven directory. So you must include /bin. It should look something like: /Users/raja/apps/apache-maven-3.5.4/bin

   # Test your Maven setup

   • Make sure to restart the Terminal or Command line prompt to load the new environment variables.
   • Run mvn -v. You should see something like below:

5. Install git from here.

   TIP

   Installing git is optional. You need this mainly to clone the demo project from the Github repository. Instead of installing git, you can simply download the Zip file from the repo. Further, If you are Mac, you already have git.

6. Install Google Chrome browser from here

7. Install a Chromedriver that's appropriate for your operating system and your Chrome browser's version from here. For example, if your Chrome browser is v67-v69, download ChromeDriver 2.41.

   • Unzip ChromeDriver to any folder of your choice.

   • Add ChromeDriver's path to your system's PATH so Selenium can find it.

   • Mac:

     • Open ~/.bash_profile file (Create one if it's missing).
     • Add export PATH="<PATH_TO_YOUR_CHROME_DRIVER>:$PATH".
       • For example, if the chromedriver is in /Users/apps/chromedriver, then it would be export PATH="/Users/apps/:$PATH.
     • Save the file and go back to the Terminal.
     • Run source ~/.bash_profile. This will load environment variables from ~/.bash_profile.

   • Windows:

     • Navigate to Computer (Right click) | Properties | Advanced System Settings | Advanced (Tab) | Environment variables | System Variables.
     • Select the line with Path key.
     • Click on Edit.
     • Add a semicolon ; to the end of the values and add the path where you have unzipped ChromeDriver.
     • For example, if the ChromeDriver is in c:\selenium\chromedriver, then append ;c:\selenium to the end of the Path.
     • Save it.

   If everything went fine, and if you typed chromedriver in the command prompt, you should see something like below:

# Step 1.2 Download the demo project

1. Clone the repo:

git clone https://github.com/applitools/tutorial-selenium-java.git

2. Go to the project folder cd tutorial-selenium-java.

3. Run mvn package. This will compile and get the project ready for execution.

# Step 1.3 Importing the project into Eclipse

The project can be run from the command line or through Eclipse. We recommend the command line option because it's faster. Also it is CI/CD friendly. However, if you want to run the tests through Eclipse, here is how to import it.

1. Navigate to File | Import... | Maven | Existing Maven Projects | Next (button)
2. Navigate to the place where you downloaded the project
3. Click Next and Import the project.

# Step 1.4 Run your first test

• From command line:

  Run $ mvn exec:java -Dexec.mainClass="com.applitools.quickstarts.App" -Dexec.args="1"

• From Eclipse:

  "Run app" menu --> Run Configurations.. --> Arguments (tab) --> Enter "1" in the "Program arguments" (section) --> Click "Run".

You should see the test run in a Chrome browser window.

    //App.java
		String viewportWidth = "1200";  // Reduce this to 800
		String viewportHeight = "750";  // Reduce this to 600
		String testName = "Login Page Java Quickstart";
		String appName = "ACME app";
		String loginPageName = "Login Page";
		String appPageName = "App Page";

# Step 1.3: Check the baseline

Login to applitools.com and see the results. Applitools app should show the results like below.

# Part 2 - Find UI bugs and analyze differences using AI

In this part, you'll run the tests again but the test will use a different url to simulate a broken UI.

# Step 2.1: Run the test again

Go to your command line and type the following command. It will test the login page (version 2) again and store the result in Applitools.

• From command line:

  Run $ mvn exec:java -Dexec.mainClass="com.applitools.quickstarts.App" -Dexec.args="2"

• From Eclipse:

  "Run app" menu --> Run Configurations.. --> Arguments (tab) --> Enter "2" in the "Program arguments" (section) --> Click "Run".

​

# Step 2.2 Analyze the result

Please switch to Applitools dashboard in your browser.

You will see a new test run with an "unresolved" status. This means Applitools is asking you to check if the differences are valid. If so, accept it and this result will become a new baseline. If not, reject it and your result will be marked as "Failed" and your previous baseline remains as is.

# Step 2.3: Click on the resulting image

# Step 2.4 Click on the "Toggle" button to see differences between the baseline and current checkpoint

# Step 2.5 Click on the Radar button to highlight differences at once

This is very handy when your app is complex and has lot of data.

# Step 2.6 Zoom in and see each difference closely

# Part 3 - Understand why Applitools AI eyes is superior to pixel-by-pixel comparison

At Applitools we have trained our AI with millions of images to look for differences in various ways. AI is also trained to ignore certain types of differences that human eyes usually ignore. We provide four different "modes" to compare differences. In this part, you will see how differences between 4 "modes" of comparisons.

# Step 3.1 Check out the "Strict" mode by selecting the option in the menu

This mode uses AI to simulate the differences that are commonly found by the human eye. It ignores some of the minor differences like "off-by-a-pixel" type errors. This help eliminate common false-positives of pixel-by-pixel comparison tools.

# Step 3.2 Check out the "Exact" mode by selecting the option in the left-menu

This mode does pixel-by-pixel comparison. This will cause lot of false-positives! This is one of the big reasons why we use AI

Notice that a lot of things in the background image is also considered as real bugs! ⚠️

# Step 3.3 Check out "Content" mode by selecting the option in the menu

The Content mode works in a similar way to Strict except for the fact that it ignores colors.

# Step 3.4 Check out the "Layout" mode by selecting the option in the left-menu

This mode shows any major differences in the layouts like a major section is removed.

In our example there are no major layout changes so if you were simply testing if the structure of the app looks good, and are using the layout mode in your code, it would succeed!

# Part 4 - Accepting 100s of changes by clicking a button instead of updating numerous tests

Now let's imagine that you did your analysis and it turns out all those differences are because of just a new version of the app. Typically this means you'd need to throw out or rewrite 100s of tests! In "Visual testing" you don't have because you didn't really write any tests 😊!

To accept 100s of changes, simply click on one of the three "Thumbs up" buttons.

There are three options:

1. Accept the differences and the checkpoint image of this test step: This option allows us to accept all the changes for this specific step and not other steps in the same test (if there are multiple steps).

2. Accept the differences and checkpoint images of all test steps with similar differences: This option allows us to accept similar differences in all the steps.

3. Accept the differences and checkpoint images of all test steps: This accepts all test steps irrespective of similar differences or not. Essentially, you get a new baseline for all test steps.

# Step 4.1: Select "Accept the differences and the checkpoint image of this test step" option

# Step 4.2: Press Save

# Step 4.3: Re-run the test

Switch to the command prompt and run:

• From command line:

  Run $ mvn exec:java -Dexec.mainClass="com.applitools.quickstarts.App" -Dexec.args="2"

• From Eclipse:

  "Run app" menu --> Run Configurations.. --> Arguments (tab) --> Enter "2" in the "Program arguments" (section) --> Click "Run".

# Step 4.4: Check the result in the Dashboard

Switch to Applitools dashboard in the browser. Press the "Refresh" button and then you should see the result marked as "Passed".

# Part 5 - Use advanced AI tools to work with real-world scenarios

In this part, you will run tests on the main app page and learn about how to deal with dynamic contents and floating contents.

# Step 5.1 Run the test on the main app

The following command opens the main app and generates the screenshot and closes it.

• From command line:

  Run $ mvn exec:java -Dexec.mainClass="com.applitools.quickstarts.App" -Dexec.args="3"

• From Eclipse:

  "Run app" menu --> Run Configurations.. --> Arguments (tab) --> Enter "3" in the "Program arguments" (section) --> Click "Run".

# Step 5.2 Run the test on the main app (version 2)

Now run the following command to open up the second version of the app so we can see differences.

• From command line:

  Run $ mvn exec:java -Dexec.mainClass="com.applitools.quickstarts.App" -Dexec.args="4"

• From Eclipse:

  "Run app" menu --> Run Configurations.. --> Arguments (tab) --> Enter "4" in the "Program arguments" (section) --> Click "Run".

​

# Step 5.3 See the differences

# Step 5.4 Dealing with Dynamic contents

Dynamic contents are contents that constantly change, for example, a clock. If you use a pixel-by-pixel comparison, your test will fail every time. Thankfully, Applitools provide a simple way to ignore a region so you can continue to visual test the rest of the page.

# Step 5.4.1 Click on the "Ignore region" option

# Step 5.4.2 Select the region around the time

# Step 5.4 Dealing with floating contents

Sometimes the data remains the same but they move or float around a bit. For example, if you center-align some data then if the data changes, the browser will move it a bit to keep it center. But this causes problems for the visual test. Again, you can use Applitools' "Floating region" option to manually add some wiggle room.

In our app, the Your nearest branch closes in: text moves sideways because it is center aligned. Let's add some wiggle room.

# Step 5.4.1 Select "Floating region" option from the menu

# Step 5.4.2 Select the area around the "Your closest branch closes in:" to add

# Step 5.4.3

Press "Thumbs up" button accept the changes.

# Step 5.4.4

Press "Save" to save it as a new baseline.

# Part 6 - Congratulations and next steps!

Applitools Eyes is a powerful platform for automated visual UI testing that supports full page screenshots, page layout matching, cross-device and browser testing, test batching, baseline branching and merging, automated baseline maintenance, collaboration features, and much more. Applitools has over 40 SDKs supporting a broad range of testing environments.

# Reference documentation

To learn more, check out the Applitools Eyes documentation and tutorials for other testing environments.

# Request a demo

If you want to see a demo of all our other features, you do request a demo

# Knowledge base and Support

You can search our Knowldege base for more information. You can also file a contact our support team and file a Ticket.


Terms & Conditions Privacy Policy GDPR© 2019 Applitools. All rights reserved.