Skip to main content

Testing web apps in Java using Selenium WebDriver and JUnit

This quickstart will show you how to visually test web apps in Java using Selenium WebDriver and JUnit. Visual testing can help you catch problems that traditional automation struggles to find. You can also leverage Applitools Ultrafast Grid to run your tests across all the major browsers in a fraction of the time as other cross-browser testing platforms.

All it takes are three short steps:

  1. Preparing your environment
  2. Getting your example project
  3. Running your tests

After setting up your machine, this quickstart should take about 15 minutes to complete.

Need extra help?

If you get stuck on this example, don't suffer in silence! Please reach out to us to get things working. We can also help you get Applitools running in your own project.

Step 1: Preparing your environment

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

  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:

  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.

Step 2: Getting your example project

Downloading the example project

There are two ways to run tests:

  1. Using Applitools Ultrafast Grid for cross-browser testing in the cloud
  2. Using Applitools Classic runner on your local machine

If you are not sure which one to pick, read Leveraging the Applitools platform. For most cases, we recommend Applitools Ultrafast Grid. We provide separate example projects for each type of runner.

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
Don't have Git?

Instead of running git clone, you can download the project as a ZIP file and extract it.

Installing the dependencies

The example project uses Apache Maven for package management. All dependencies are listed in the project's pom.xml file. If you are using a Java IDE, then the IDE should install the dependencies and build the project for you. However, you may also install dependencies from the command line using the following command:

mvn install
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, then add the latest version of the eyes-selenium-java5 package to the project's pom.xml file.

The eyes-selenium-java5 package includes a dependency for the Selenium 3 package. If you want to use Selenium 4, then add the latest 4.x version of the selenium-java package to the project's pom.xml file as well.

Walking through the code

Test setup code is slightly different between Ultrafast Grid and the Classic runner.

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. With the Ultrafast Grid, you can specify different browser types, viewport sizes, and even mobile devices.

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


Step 3: Running your tests

Setting Applitools variables

Before running the visual test, you must find your Applitools API key and set it as an environment variable named APPLITOOLS_API_KEY. You can set this variable through your IDE, or you can set it from the command line like this:

export APPLITOOLS_API_KEY=<your-api-key>
Having trouble with environment variables?

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

// Change the following line:
// applitoolsApiKey = System.getenv("APPLITOOLS_API_KEY");
applitoolsApiKey = "<your-api-key>";

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

You may also need to set your 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. (If you are using a free Applitools account, then use the public server.)

Launching visual tests

The easiest way to launch this test is through a Java IDE. Just make sure to set the APPLITOOLS_API_KEY environment variable in your test's run configuration.

You can also launch this test from the command line using the following Maven command, which works for both example projects on any operating system:

mvn test

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

After your tests run, you should see results in the Applitools Eyes dashboard. You can log into the dashboard at eyes.applitools.com or at the address for your private Applitools Eyes server.

If you run tests with the Applitools Ultrafast Grid, then the tests will run one time on the local machine, and then they will upload snapshots to render on each target configuration in the cloud. The dashboard will show a separate result for each rendering. If you run tests with the Applitools Classic runner, then the dashboard will show the one snapshot from your local machine.

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");

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.

Need extra help?

Again, it's okay. If you get stuck on this example, don't suffer in silence! Please reach out to us to get things working. We can also help you get Applitools running in your own project.

Taking the next steps with Applitools

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

Resources for next steps:

  1. 🤖 Learning how visual testing works
  2. ↔️ Setting match levels for visual checkpoints
  3. 💥 Troubleshooting common issues
  4. 🐞 Reporting bugs
  5. 🗺 Detailed overview of visual testing with Applitools

You can also: