Skip to main content

Comparing image files and PDFs with the Image Tester CLI

Applitools Image Tester enables you to run visual tests on image files and PDFs. It's a great tool for detecting differences in documents and screenshots over time. Image Tester is distributed as a standalone Java Archive (JAR) file, which can be executed directly from the command line interface (CLI) or invoked as a process by any programming language.

After preparing your environment, this three-step 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 9 or higher. To install it, follow the JDK Installation Guide.

Step 2: Getting your example project​

The example project is located at https://github.com/applitools/example-image-tester-cli. Clone this repository to your local machine:

git clone https://github.com/applitools/example-image-tester-cli.git
cd example-image-tester-cli
Don't have Git?

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

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 may set it through your IDE (if applicable), or you may set it from the command line like this:

export APPLITOOLS_API_KEY=<your-api-key>

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

Executing the example tests​

The example project contains a set of image files and PDFs for testing:

  • The files directory provides "original" version of the images and PDFs.
  • The files_modified directory provides visually modified versions of the same files.

It also contains the Image Tester JAR file (version 3.1.3) so you don't need to download it separately for this quickstart.

Start by setting baselines using the original files by running:

java -jar ImageTester_3.1.3.jar -fb "Example: Image Tester CLI" -f files/

The -fb option provides the batch name. The -f option provides the path to the directory containing image files and PDFs. Once testing is complete, you should see results in the Eyes Test Manager. You can log into the Test Manager at eyes.applitools.com or at the address for your private Applitools Eyes server.

Then, check for visual differences in the modified files by running:

java -jar ImageTester_3.1.3.jar -fb "Example: Image Tester CLI" -f files_modified/

They should yield "unresolved" results for you to review in the Test Manager. 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.

Executing your own tests​

You can run Image Tester against any image files and PDFs. To run your own tests, download the latest Image Tester JAR file from https://github.com/applitools/ImageTester/releases/latest, and execute it like this:

java -jar ImageTester_<version>.jar -f <path-to-images>
Advanced Options

The Image Tester tool has many features and options to run your tests. To see the full list of options, please consult the Image Tester README.

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