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.
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:
An Applitools account, which you can register for free.
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
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:
- macOS and Linux
- Windows
export APPLITOOLS_API_KEY=<your-api-key>
set 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
filesdirectory provides "original" version of the images and PDFs. - The
files_modifieddirectory 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.
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>
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.
