Transcripted Summary
Applitools is not limited to verifying websites and mobile apps. It also works for PDFs. In this chapter, I'll go over how to use the Applitools ImageTester.jar to verify PDF forms.
The very first step is to download the jar file, and by using ImageTester.jar you can verify PDF forms from the command line. I'll also show you how you can utilize this within your automation code.
# Visually Verifying PDF on the Command Line
So I've downloaded the ImageTester.jar, and I've moved it to the resources directory within my automation project.
Here we are within my automation project, and here is the ImageTester.jar. Notice that I also have a directory here called Invoice_PDFs, and inside of there I have a PDF file. Now, we can verify this PDF file right here by running a command.
The command to execute the PDF comparison is
java -jar ImageTester.jar
There are also two required arguments. The -k argument is where you specify your Applitools API key. You can paste your API key directly here, or reference an environment variable if you have it saved, like I do here.
The second required argument is the -f which is used to specify a file or directory. If I reference a directory, it will verify all of the PDFs (and images) inside of that directory, and it will verify that as a batch. We've seen how batches work in the last chapter. This will run as a suite, and it will be reported to the Test Manager dashboard as such. Alternativey, you can use -f to specify an individual PDF or image file. If you specify a file, it will run as a single test.
I'm going to go ahead and specify the file I have saved, INV12345.pdf.
java -jar ImageTester.jar -k $APLITOOLS_API_Key -f Invoice_PDFs/INV12345.pdf
When I execute this for the first time, it will take a baseline of the PDF and output a status of [New].
[New] - INV12345.pdf
Here's what it looks like in the Test Manager dashboard.
Now, of course we want to run it again just to make sure that it's working. I'm going to re-run this command, and this time we should see that it passes.
java -jar ImageTester.jar -k $APLITOOLS_API_Key -f Invoice_PDFs/INV12345.pdf
[Passed] - INV12345.pdf
# Visually Verifying PDFs within Code
Now I want to show you how you can use this within the scope of code, because as an automation engineer, I'm thinking that you are probably running some UI tests where you need to enter some fields of a form, and then maybe the site generates a PDF. You download that PDF form, and then you need to run the verification.
You can do that right from the midst of your code. Let me show you how.
I'm going to use this example [Invoice Simple App] (https:/app.invoicesimple.com) to create an invoice.
I fill out all this data, add a logo, choose a border color, etc. The ImageChecker is not limited just to text. It'll verify the logo image, the colors, everything will be verified for us.
Within my test automation, I will use Selenium WebDriver to enter data for all of these fields and create the invoice. Once I create the invoice, this app will allow me to download that invoice. Once I do that, I can click the button to download PDF.
I've written a new test. I've made a new class called PDFTests and written a new test that tests invoices.
public class PDFTests extends BaseTests {
@Test
public void testInvoices() throws IOException, InterruptedException {
driver.get(System.getProperty("sites.invoices.url"));
String invoiceNumber = "INV12345";
//omitted Selenium code to complete the form and download it
File downloadedPDF = new File("/Users/angie/Downloads/" + invoiceNumber + ".pdf");
String destination = "resources/Invoice_PDFs/" + invoiceNumber + ".pdf";
Assert.assertTrue(invoiceNumber + ".pdf file was not moved to test location",
FileUtils.moveFile(downloadedPDF, destination));
Assert.assertTrue("Error validating PDF", EyesManager.validatePDF(destination));
}
}
I fill in the invoice with all of these details. Then I click the PDF button.
When I download this invoice, it's going to download to the default directory on my computer for downloads, but I want to tell Applitools to verify a specific file within my test directory. Technically, I could just tell ImageTester.jar to look in my Downloads directory and verify that specific file name. That would work, but I want to move the file to my test directory. So, I'll show you how to programmatically move the file before verifying it.
Once the file is moved, I invoke the visual validation. This is the EyesManager.validatePDF method:
public static boolean validatePDF(String filepath) throws IOException, InterruptedException {
String command = String.format(
"java -jar resources/ImageTester.jar -k %s -f %s",
System.getProperty("applitools.api.key"),
filepath);
Process process = Runtime.getRuntime().exec(command);
process.waitFor();
String stream = IOUtils.toString(process.getInputStream(), "UTF-8");
System.out.println(stream);
if(stream != null && stream.contains("Mismatch")){
return false;
}
return true;
}
Our EyesManager already had all of these validates, so I just made another one for validatePDF which takes in the file path. And I've added that command that we used on the command line, that java -jar .
There's this Runtime method that you can use in Java called exec, basically short for execute. So this code is saying "execute this command". And that will give us a Process object. It's really important to make sure that you put this process.waitFor,because without it, the Java code would immediately go to the next line without waiting for the process to complete. If you remember, from the command line, it did take a couple of seconds for Applitools to actually verify the file, so we want to wait until we get a prompt back. And then we can move on.
Next, I'm basically getting the input stream, so this is what was printed out to the console. And I'm going to print that out so we can have it just in our results for the tests. You can basically use your logger to add this to your test log files.
Finally I'm going to do a little check to see if the output from that command contained the word "Mismatch." Now we saw where it was New, and we saw where it was Passed, but if those versions of the PDF differed, then we would see Mismatch as the status.
So if it contains Mismatch, I'm going to return false. If not, return true. And then in our test, that's where we're doing the assertion on that.
So that's how you verify the PDFs. We'll go ahead and run this now.
Since our PDF has changed, I've made it very different now. When we run this test, it should give us a failure.
Now, notice here, remember we added something different when we did it versus the UI. So this is the baseline. Notice here we have the price as $54.99, and we only have the dress here. But on our test, I didn't just do the dress, I also added leggings and shoes, and so this price got a lot bigger. So you notice that the differences are highlighted.
We can accept this as our new baseline, and then if we run this test again, then it will pass.
Okay, let's run this one more time now that we've updated our baseline to reflect our test. And now we see that it passed.
Okay, now there's one more thing that we need to consider with this PDF testing.
Let me take you to the dashboard. If we take a closer look at this PDF, notice that the date on the invoice is today's date. This is the date that this was generated. So, if this happened to run again tomorrow, this date is going to be different, and our test will fail.
So we can apply Ignore Regions on PDFs just like we can do for any other visual test in the Test Manager. I'm going to add an Ignore Region on the date which is basically saying 'don't worry about verifying this piece of the doc'. Now when this test runs tomorrow or next year, this part won't be considered, and it'll just verify everything else.
There you have it, that's the PDF verification with Applitools.
# Advanced Options for Verifying PDFs
There are additional options you can use for your PDF validation. You can see them on the PDF forms tutorial on the Applitools site.
