percy-java-selenium on GitHub

Setup

---

Add percy-java-selenium to your project dependencies. If you're using Maven:

<dependency>
  <groupId>io.percy</groupId>
  <artifactId>percy-java-selenium</artifactId>
  <version>0.0.3</version>
</dependency>

If you're using a different build system, see https://search.maven.org/artifact/io.percy/percy-java-selenium for details for your specific system.

Install the Percy agent, which will upload snapshots on your behalf. It is available as a Node module, and you can install it using npm.

To install locally for your project:

$ npm install --save-dev @percy/agent

This will install the percy agent executable in a node_modules/ folder inside the current working directory. You can access the agent's executable at ./node_modules/.bin/percy.

In order to start creating snapshots from your Java Selenium scripts or tests, you'll need to import the io.percy.selenium.Percy function from the percy-java-selenium library. You will need to do this in each file from which you want to take snapshots:

import io.percy.selenium.Percy;

After you instantiate a Selenium WebDriver, create a new Percy instance:

Percy percy = new Percy(driver);

Use percy.snapshot(...) to generate a snapshot:

@Test
public void loadsHomePage() {
    driver.get("http://example.com");

    // Take a Percy snapshot.
    percy.snapshot("Home Page");
}

Before you can successfully run Percy, the PERCY_TOKEN environment variable must be set:

# Windows
$ set PERCY_TOKEN=<your token here>

# Unix 
$ export PERCY_TOKEN=<your token here>

Finally, wrap your program or test runner command in the percy exec command. This will start a Percy agent to receive snapshots from your tests and upload them to your Percy dashboard. For example, if you are using Maven to run your tests, your new test command becomes:

npx percy exec -- mvn test

Note the double dash, --, between percy exec and your test run command.

That's it! Now, whenever CI runs, a snapshot of the app in that state will be uploaded to Percy for visual regression testing!

For an example showing how to add Percy snapshots to an existing Selenium Java test suite, see https://github.com/percy/example-percy-java-selenium/pull/3.

Configuration

---

Percy constructor:

new Percy(driver)

driver is an object that implements the org.openqa.selenium.WebDriver interface.

Percy snapshot methods:

void snapshot(String name)
void snapshot(String name, @Nullable List<Integer> widths)
void snapshot(String name, @Nullable List<Integer> widths, @Nullable Integer minHeight)

snapshotName is a String that will be used as the snapshot name. It can be any string that makes sense to you to identify the page state. It should be unique and remain the same across builds.

widths is a List<Integer> representing the browser widths at which you want to take snapshots.

minHeight is an Integer specifying the minimum height of the resulting snapshot, in pixels. Defaults to 1024px.

Examples

WebDriver driver = new ChromeDriver();
Percy percy = new Percy(driver);
// ... use driver to navigate to the app and interact with it ..

percy.snapshot("Home page");
percy.snapshot("Home page responsive", Arrays.asList(768, 992, 1200));
percy.snapshot("Home page tall", Arrays.asList(768, 992, 1200), 2000);

Global Configuration

You can also configure Percy to use the same options over all snapshots. To see supported configuration including widths read our Configuration doc.