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>[3.0.0, 4.0.0)</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 {
			// Call getTestInfoForPart to get the appropriate test information.
			HashMap<String, String> testInfo = App.getTestInfoForPart(args);

			// 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);
		}

	}
}

Notes

  1. Everything between eyes.open and eyes.close is called a Test.
  2. The eyes.checkWindow is the code that takes the picture and uploads the image to our AI eyes server.
  3. You can have multiple checkWindow if you are navigating multiple pages in a single test.

Also note that because this example has only one test, the code you include to add Applitools may look like a lot. But once you set things up, the only extra code you will add will be "eyes.checkWindow()", "eyes.checkRegion()" etc even if there are hundreds of tests.

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 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:

login page

App page:

App page

Step 1.1: Install Prerequisites

TIP

The instructions are elaborate and are for a brand new machine. You may skip most of it(Steps 3, 4, 5 and 6) if you already have Java, JAVA_HOME, Maven, Chrome browser, Chromedriver all set up properly.

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

  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.
  1. 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: Maven test result
  2. 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.

  3. Install Google Chrome browser from here

  4. 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: Chromedriver

Step 1.2 Download the demo project

  1. Clone the repo:

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

TIP

Optionally, download the Zip file and extract it from the git repo.

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

  2. 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.

Important Tip: How to load Environment variables into Eclipse / IntelliJ

If you are running the tests through an editor like Eclipse or IngelliJ. Open the editor directly from the Terminal (and not by clicking on the editor icon).

✴️ To do that, run "open /path/to/Eclipse or IntelliJ.app" from the Terminal.

This will load all the environment variables that's set in that Terminal into Eclipse/IntelliJ! This will avoid you hard-coding paths and keys for things as webdriver.chrome.driver, APPLITOOLS_API_KEY

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.

Potential problems and their solutions

  1. You may see an error that says Chrome driver is not found. This means that either the Chrome driver is not downloaded or it is in your PATH. If you simply type chromedriver and if you see unknown command then chromedriver is not in your PATH.
  2. You may see an error that says "Could not set Viewport". This means that your computer monitor's viewport size is smaller than what the test app is using. If so, open the App.java and reduce viewPortWidth and viewPortHeight. Keep reducing until it's smaller than your monitor's size.


Β 
Β 






    //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.

Baseline 1

TIP

The initial run is automatically accepted as a baseline.

  1. If you don't see anything, click on the "Refresh" button

  2. The "Thumbs up" button is used to accept the image as a baseline

  3. The "Save" button is used to save a new baseline image

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.

TIP

Remember to click on the "Refresh" button in the left panel to see the new test result

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.3

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

Step 2.4

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.5

Step 2.6 Zoom in and see each difference closely

Step 2.6

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.

Part 3

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.

TIP

This is the default mode. You can set whichever mode you want in code.

Step 3.1

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.2

WARNING

Do not use this mode unless really necessary as it does pixel-by-pixel comparison and may lead to false positives.

Most other Visual testing tools/methods become useless because they use a simple pixel-by-pixel comparison.

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.

TIP

The content level can be useful if your website includes different colors which are not relevant for your tests

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!

Step 3.4

TIP

For most scenarios, we recommend using either the "Strict" mode or the "Layout" mode. Use "Content" and "Exact" modes for special cases.

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 😊!

Note

We'll go over the few lines of code you will add to import Applitools and generate images but that's about all the code you'll write. And once you wrote it, it won't change!

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.2

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". Step 4.4

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. Part 5

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".

A note about taking a full page screenshot

Note that the main app is pretty long and goes below the fold (or, below the current viewport). So Applitools scrolls down the page twice. First to load everything below the scroller. Then it goes back up to the top of the page and scrolls down the second time to take the screenshot.

This is because we have eyes.setForceFullPageScreenshot(true); //force scrolling

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.3

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.2

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

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Β© 2018 Applitools. All rights reserved.

Last Updated: 10/16/2018, 1:53:23 PM