Tutorial: Selenium Java JUnit with the Ultrafast Grid

This tutorial will show you how to automate visual tests using the Applitools Ultrafast Grid with Selenium in Java. Applitools Ultrafast Test Cloud can help you catch functional and visual problems that traditional automation struggles to find. It can also help you to scale your tests to cover all browsers and devices in seconds.

In this tutorial, you will:

  1. Set up your local machine for testing.
  2. Clone the example project repository.
  3. Learn how to automate visual testing with Applitools Eyes.
  4. Run the visual tests and review results in the Applitools dashboard.

After setting up your machine, this tutorial should take about 15 minutes to complete. If you get stuck along the way, please reach out to us for help!

Quickstart

If you prefer a quickstart instead of a full tutorial, clone the example repository and follow the README instructions!

Recognizing project structure

The example project uses:

Setting up your machine

You'll need a few things to run this tutorial:

  1. An Applitools account, which you can register for free.

  2. The Java Development Kit (JDK), version 8 or higher.

  3. A good Java editor, such as:

    1. JetBrains IntelliJ IDEA
    2. Eclipse IDE
    3. Apache NetBeans
    4. Visual Studio Code
  4. Apache Maven for project builds and dependencies.

    Installing Maven

    If you use JetBrains IntelliJ IDEA, Eclipse IDE, or Apache NetBeans, then you do not need to install Maven separately because these IDEs come bundled with Maven.

    Otherwise, you will need to install Maven and add it to the system PATH variable. Follow instructions on the Installing Apache Maven page. On macOS and Linux, you can install Maven with Homebrew by running brew install maven.

    If you installed Maven separately from an IDE, then you can test that Maven is working by running the mvn -v command to print its version.

  5. An up-to-date version of Google Chrome.

  6. A corresponding version of ChromeDriver.

    Installing ChromeDriver

    The major version numbers of Chrome and ChromeDriver must be the same. Otherwise, Selenium WebDriver may raise an exception when it is initialized. For example, Chrome v101 requires ChromeDriver v101.

    ChromeDriver must be installed into a directory covered by the system PATH variable. Follow the instructions on Selenium's Install browser drivers page. On macOS and Linux, the recommended location for the chromedriver executable is the /usr/local/bin directory.

    You can test that ChromeDriver is working by running the chromedriver -v command to print its version.

Downloading the example project

The example project is located at https://github.com/applitools/example-selenium-java-junit-ufg. Clone this repository to your local machine:

$ git clone https://github.com/applitools/example-selenium-java-junit-ufg.git
$ cd example-selenium-java-junit-ufg
1
2

Note: If you don't have Git installed, then instead of running git clone, you can download the project as a ZIP file and extract it.

Understanding the dependencies

The example project is a standard Java Maven project. The minimum version that the Applitools SDK supports is Java 8. Thus, the pom.xml file sets the project to use Java 8:

 <properties>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
 </properties>
1
2
3
4

Note: You can set a higher version of Java to match your JDK.

Since the project needs the Applitools Eyes SDK for Selenium and JUnit 5, pom.xml also contains the following dependencies:

 <dependencies>
     <dependency>
         <groupId>com.applitools</groupId>
         <artifactId>eyes-selenium-java3</artifactId>
         <version>3.213.0</version>
         <scope>test</scope>
     </dependency>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter</artifactId>
         <version>5.8.2</version>
         <scope>test</scope>
     </dependency>
 </dependencies>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Adding Applitools to Another Maven Project?

This example project already has the Applitools Eyes SDK as a dependency. If you want to add the Applitools Eyes SDK as a new dependency to another Maven project, simply copy and paste the <dependencies> XML block above into the project's pom.xml file.

Version Warning

Do not use eyes-selenium-java3 version 5.x.

The eyes-selenium-java3 includes the dependency for the Selenium 3 package. If you want to use Selenium 4, add the following dependency to override the old one:

    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.2.1</version>
        <scope>test</scope>
    </dependency>
1
2
3
4
5
6

Understanding the code

The project contains one visual test case, which is located at src/test/java/com/applitools/example/AcmeBankTests.java.

AcmeBankTests is a JUnit 5 test class that covers login behavior for the ACME Bank demo web app. It uses the Applitools Eyes SDK to execute the test across multiple browsers in Applitools Ultrafast Grid.

In-line comments explain every section of its code. Read it top to bottom to understand how it works:

package com.applitools.example;

import com.applitools.eyes.BatchInfo;
import com.applitools.eyes.RectangleSize;
import com.applitools.eyes.TestResultsSummary;
import com.applitools.eyes.selenium.BrowserType;
import com.applitools.eyes.selenium.Configuration;
import com.applitools.eyes.selenium.Eyes;
import com.applitools.eyes.selenium.fluent.Target;
import com.applitools.eyes.visualgrid.model.DeviceName;
import com.applitools.eyes.visualgrid.model.ScreenOrientation;
import com.applitools.eyes.visualgrid.services.RunnerOptions;
import com.applitools.eyes.visualgrid.services.VisualGridRunner;
import org.junit.jupiter.api.*;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

import java.time.Duration;

public class AcmeBankTests {
    // This JUnit test case class contains everything needed to run a full visual test against the ACME bank site.
    // It runs the test once locally,
    // and then it performs cross-browser testing against multiple unique browsers in Applitools Ultrafast Grid.

    // Test control inputs to read once and share for all tests
    private static String applitoolsApiKey;
    private static boolean headless;

    // Applitools objects to share for all tests
    private static BatchInfo batch;
    private static Configuration config;
    private static VisualGridRunner runner;

    // Test-specific objects
    private WebDriver driver;
    private Eyes eyes;

    @BeforeAll
    public static void setUpConfigAndRunner() {
        // This method sets up the configuration for running visual tests in the Ultrafast Grid.
        // The configuration is shared by all tests in a test suite, so it belongs in a `BeforeAll` method.
        // If you have more than one test class, then you should abstract this configuration to avoid duplication.

        // Read the Applitools API key from an environment variable.
        // To find your Applitools API key:
        // https://applitools.com/tutorials/getting-started/setting-up-your-environment.html
        applitoolsApiKey = System.getenv("APPLITOOLS_API_KEY");

        // Read the headless mode setting from an environment variable.
        // Use headless mode for Continuous Integration (CI) execution.
        // Use headed mode for local development.
        headless = Boolean.parseBoolean(System.getenv().getOrDefault("HEADLESS", "true"));

        // Create the runner for the Ultrafast Grid.
        // Concurrency refers to the number of visual checkpoints Applitools will perform in parallel.
        // Warning: If you have a free account, then concurrency will be limited to 1.
        runner = new VisualGridRunner(new RunnerOptions().testConcurrency(5));

        // Create a new batch for tests.
        // A batch is the collection of visual checkpoints for a test suite.
        // Batches are displayed in the dashboard, so use meaningful names.
        batch = new BatchInfo("Applitools Example: Selenium Java JUnit with the Ultrafast Grid");

        // Create a configuration for Applitools Eyes.
        config = new Configuration();

        // Set the Applitools API key so test results are uploaded to your account.
        // If you don't explicitly set the API key with this call,
        // then the SDK will automatically read the `APPLITOOLS_API_KEY` environment variable to fetch it.
        config.setApiKey(applitoolsApiKey);

        // Set the batch for the config.
        config.setBatch(batch);

        // Add 3 desktop browsers with different viewports for cross-browser testing in the Ultrafast Grid.
        // Other browsers are also available, like Edge and IE.
        config.addBrowser(800, 600, BrowserType.CHROME);
        config.addBrowser(1600, 1200, BrowserType.FIREFOX);
        config.addBrowser(1024, 768, BrowserType.SAFARI);

        // Add 2 mobile emulation devices with different orientations for cross-browser testing in the Ultrafast Grid.
        // Other mobile devices are available, including iOS.
        config.addDeviceEmulation(DeviceName.Pixel_2, ScreenOrientation.PORTRAIT);
        config.addDeviceEmulation(DeviceName.Nexus_10, ScreenOrientation.LANDSCAPE);
    }

    @BeforeEach
    public void openBrowserAndEyes(TestInfo testInfo) {
        // This method sets up each test with its own ChromeDriver and Applitools Eyes objects.

        // Open the browser with the ChromeDriver instance.
        // Even though this test will run visual checkpoints on different browsers in the Ultrafast Grid,
        // it still needs to run the test one time locally to capture snapshots.
        driver = new ChromeDriver(new ChromeOptions().setHeadless(headless));

        // Set an implicit wait of 10 seconds.
        // For larger projects, use explicit waits for better control.
        // https://www.selenium.dev/documentation/webdriver/waits/
        // The following call works for Selenium 4:
        driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));

        // If you are using Selenium 3, use the following call instead:
        // driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);

        // Create the Applitools Eyes object connected to the VisualGridRunner and set its configuration.
        eyes = new Eyes(runner);
        eyes.setConfiguration(config);

        // Open Eyes to start visual testing.
        // It is a recommended practice to set all four inputs:
        eyes.open(
                driver,                                         // WebDriver object to "watch"
                "ACME Bank Web App",                            // The name of the app under test
                testInfo.getDisplayName(),                      // The name of the test case
                new RectangleSize(1024, 768));    // The viewport size for the local browser
    }

    @Test
    public void logIntoBankAccount() {
        // This test covers login for the Applitools demo site, which is a dummy banking app.
        // The interactions use typical Selenium WebDriver calls,
        // but the verifications use one-line snapshot calls with Applitools Eyes.
        // If the page ever changes, then Applitools will detect the changes and highlight them in the dashboard.
        // Traditional assertions that scrape the page for text values are not needed here.

        // Load the login page.
        driver.get("https://demo.applitools.com");

        // Verify the full login page loaded correctly.
        eyes.check(Target.window().fully().withName("Login page"));

        // Perform login.
        driver.findElement(By.id("username")).sendKeys("applibot");
        driver.findElement(By.id("password")).sendKeys("I<3VisualTests");
        driver.findElement(By.id("log-in")).click();

        // Verify the full main page loaded correctly.
        // This snapshot uses LAYOUT match level to avoid differences in closing time text.
        eyes.check(Target.window().fully().withName("Main page").layout());
    }

    @AfterEach
    public void cleanUpTest() {

        // Quit the WebDriver instance.
        driver.quit();

        // Close Eyes to tell the server it should display the results.
        eyes.closeAsync();

        // Warning: `eyes.closeAsync()` will NOT wait for visual checkpoints to complete.
        // You will need to check the Applitools dashboard for visual results per checkpoint.
        // Note that "unresolved" and "failed" visual checkpoints will not cause the JUnit test to fail.

        // If you want the JUnit test to wait synchronously for all checkpoints to complete, then use `eyes.close()`.
        // If any checkpoints are unresolved or failed, then `eyes.close()` will make the JUnit test fail.
    }

    @AfterAll
    public static void printResults() {

        // Close the batch and report visual differences to the console.
        // Note that it forces JUnit to wait synchronously for all visual checkpoints to complete.
        TestResultsSummary allTestResults = runner.getAllTestResults();
        System.out.println(allTestResults);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

Preparing for test execution

Before running the visual test, you must find your Applitools API key and set it as an environment variable named APPLITOOLS_API_KEY.

On macOS and Linux:

$ export APPLITOOLS_API_KEY=<your-api-key>
1

On Windows:

> set APPLITOOLS_API_KEY=<your-api-key>
1

Environment Variable Trouble

If you have trouble setting the APPLITOOLS_API_KEY environment variable, you can hard-code your API key into the test case like this:

// applitoolsApiKey = System.getenv("APPLITOOLS_API_KEY");
applitoolsApiKey = "<your-api-key>";
1
2

However, be warned: hard-coding secrets is poor practice. Do this only temporarily for debugging, and never commit hard-coded secrets to version control.

Applitools Eyes Server

By default, tests will use the public Applitools Eyes server at eyes.applitools.com. However, if your team is using a private Applitools Eyes server, you can target it by setting the APPLITOOLS_SERVER_URL environment variable.

Running the visual test

To run the test, run this Maven command (which works for any OS):

$ mvn test
1

By default, the test will run headlessly. To run it headed, set the HEADLESS environment variable to false.

You can also run the test through an IDE like IntelliJ IDEA or Eclipse. Just make sure to set the APPLITOOLS_API_KEY environment variable in your test's run configuration.

Once your tests run, you should see results in the Applitools dashboard. For your batch, there should be 5 tests (one for each browser configuration), each with 2 visual snapshots.

You can also change the web page to inject visual bugs:

// driver.get("https://demo.applitools.com");
driver.get("https://demo.applitools.com/index_v2.html");
1
2

If you rerun the tests, then they should yield "unresolved" results for you to review. Visual differences will be highlighted in magenta. It's up to you to accept (👍) or reject (👎) the changes. Applitools will remember your decisions for future analysis.

Having Trouble?

Don't suffer in silence! Let us help you. Please reach out to us to get your project working.

Taking the next steps

Congratulations on completing this tutorial! There's still so much to learn about visual testing with Applitools, but you're off to a great start.

Here are resources for your next steps:

  1. 🤖 How Applitools Works
  2. 🖼 Analyzing Differences
  3. 🐞 Reporting Bugs
  4. 💥 Troubleshooting Common Issues
  5. 🗺 Detailed overview of visual testing with Applitools
  6. 👀 Docs for the Applitools Eyes Selenium 3 Java SDK

You can also:

Last Updated: 6/15/2022, 2:04:03 PM