Percy PDF testing

Learn how to visually test and compare PDF files across multiple releases.

This percy-pdf code repository provides an approach to compare Portable Document Format (PDF) files using Percy for visual testing requirements across multiple application releases.

Get started

Step 1: Organize your PDF files

Copy the PDF files that you want to visually compare into the projects folder within this repository. Ensure that these PDF documents are grouped based on <project-name> and then <release-version>. A typical directory structure looks like this:

projects/
  insurance-policy-docs/          # <-- your-project-name-folder
    golden-copy/                  # <-- your-baseline-release-folder
      pdf-file-1.pdf
      pdf-file-2.pdf
      pdf-file-3.pdf
    release-v2/                   # <-- your-another-release-folder
      pdf-file-1.pdf
      pdf-file-2.pdf
      pdf-file-3.pdf
    release-v3/                   # <-- your-another-release-folder
      pdf-file-1.pdf
      pdf-file-2.pdf
      pdf-file-3.pdf

Step 2: Create a PDF run info config file

Create a PDF run info config file within the ./configs folder. Sample config files are available at ./configs.

Step 3: Set up a Percy account

Create an account on Percy and create a new Percy Web project. Note the project-specific PERCY_TOKEN, as you will need it when triggering the project builds.

Step 4: Clone the repository

Clone this repository and navigate to the project folder:

git clone git@github.com:BrowserStackCE/percy-pdf.git
cd percy-pdf

Step 5: Install Node.js

Use the latest LTS version of Node.js. You can install it from here.

Step 6: Install dependencies

Install the repository dependencies:

npm install

Step 7: Set the environment variable

Export the environment variable PERCY_TOKEN, obtained in step 3, using the command below.

For *nix-based and Mac machines:

export PERCY_TOKEN=<percy-project-token>

For Windows:

set PERCY_TOKEN=<percy-project-token>

Step 8: Trigger the run

Trigger the run using the following command:

npm test -- <run-info-config-file-path.yml> <Optional PORT Param. Default 8080>

Examples:

npm test -- configs/getting-started-scenarios/01_pdf-docs-run-info-baseline.yml
npm test -- configs/getting-started-scenarios/01_pdf-docs-run-info-release2.yml

If you want to provide a dynamic port value for the web server, provide the PORT as the second argument to the command:

npm test -- <run-info-config-file-path.yml> <Optional PORT Param. Default 8080>

Examples:

npm test -- configs/getting-started-scenarios/01_pdf-docs-run-info-baseline.yml 8081
npm test -- configs/getting-started-scenarios/01_pdf-docs-run-info-release2.yml 8081

Step 9: Trigger advanced scenarios

You can trigger the advanced scenario in a similar fashion once you have reviewed the advanced PDF run config file flags (and have relevant use cases), as documented in the PDF run config file section as follows:

npm test -- <run-info-config-file-path.yml>

Examples:

npm test -- configs/advanced-scenarios/01_pdf-docs-run-info-baseline.yml
npm test -- configs/advanced-scenarios/01_pdf-docs-run-info-release2.yml

PDF run config file

The PDF Run Info file provides several flags that specify information about the PDF documents for visual comparison. This section details all the flags.

Mandatory flags

These flags are required in every PDF run config file to define the basic comparison parameters.

Optional flags

These flags provide additional customization options for PDF comparison workflows.

Things to know

• PDF file matching: The script identifies PDF files to compare based on matching file names across different release directories. For example, insurance-policy-docs/release-v2/pdf-file-1.pdf compares against insurance-policy-docs/golden-copy/pdf-file-1.pdf.

• Page exclusion limitation: The excludePages flag within the PDF Docs Run Info Config file does not allow excluding PDF Page 1 and the second-to-last page.

Need more support? Contact BrowserStack.