Percy visual testing for Java Selenium.
Install/update @percy/cli
dev dependency (requires Node 14+):
$ npm install --save-dev @percy/cli
Install maven:
$ brew install mvn
Run tests:
npm test
npm install @percy/cli
:
$ npm install --save-dev @percy/cli
Add percy-java-selenium to your project dependencies. If you're using Maven:
<dependency>
<groupId>io.percy</groupId>
<artifactId>percy-java-selenium</artifactId>
<version>1.2.0</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.
This is an example test using the percy.snapshot
function.
// import ...
import io.percy.selenium.Percy;
public class Example {
private static WebDriver driver;
private static Percy percy;
public static void main(String[] args) {
FirefoxOptions options = new FirefoxOptions();
options.setHeadless(true);
driver = new FirefoxDriver(options);
percy = new Percy(driver);
driver.get("https://example.com");
percy.snapshot("Java example");
}
}
Running the test above normally will result in the following log:
[percy] Percy is not running, disabling snapshots
When running with percy exec
, and your project's
PERCY_TOKEN
, a new Percy build will be created and snapshots will be uploaded to your project.
$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [java test command]
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Snapshot taken "Java example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!
The snapshot method arguments:
percy.snapshot(name, widths[], minHeight, enableJavaScript, percyCSS, scope, sync, responsiveSnapshotCapture)
name
(required) - The snapshot name; must be unique to each snapshot- Additional snapshot options (overrides any project options):
widths
- An array of widths to take screenshots atminHeight
- The minimum viewport height to take screenshots atenableJavaScript
- Enable JavaScript in Percy's rendering environmentpercyCSS
- Percy specific CSS only applied in Percy's rendering environmentscope
- A CSS selector to scope the screenshot tosync
- For getting syncronous results https://www.browserstack.com/docs/percy/advanced/sync-comparison-resultsresponsiveSnapshotCapture
- For capturing snapshot of responsive websites
We built a tool to help automate migrating to the new CLI toolchain! Migrating can be done by running the following commands and following the prompts:
$ npx @percy/migrate
? Are you currently using percy-java-selenium? Yes
? Install @percy/cli (required to run percy)? Yes
? Migrate Percy config file? Yes
This will automatically run the changes described below for you.
If you're coming from a pre-3.0 version of this package, make sure to install @percy/cli
after
upgrading to retain any existing scripts that reference the Percy CLI
command. You will also want to uninstall @percy/agent
, as it's been replaced
by @percy/cli
.
$ npm uninstall @percy/agent
$ npm install --save-dev @percy/cli
If you have a previous Percy configuration file, migrate it to the newest version with the
config:migrate
command:
$ percy config:migrate
percy.screenshot(driver, name, options)
[ needs @percy/cli 1.27.0-beta.0+ ];
This is an example test using the percy.screenshot
method.
// import ...
import io.percy.selenium.Percy;
public class Example {
public static void main(String[] args) throws MalformedURLException, InterruptedException {
DesiredCapabilities caps = new DesiredCapabilities();
// Add caps here
WebDriver driver = new RemoteWebDriver(new URL(URL), caps);
Percy percy = new Percy(driver);
percy.screenshot("Screenshot 1");
driver.quit();
}
}
driver
(required) - A selenium driver instancename
(required) - The screenshot name; must be unique to each screenshotoptions
(optional) - There are various options supported by percy.screenshot to server further functionality.sync
- Boolean value by default it falls back to false, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+]fullPage
- Boolean value by default it falls back tofalse
, Takes full page screenshot [From CLI v1.27.6+]freezeAnimatedImage
- Boolean value by default it falls back tofalse
, you can passtrue
and percy will freeze image based animations.freezeImageBySelectors
- List of selectors. Images will be freezed which are passed using selectors. For this to workfreezeAnimatedImage
must be set to true.freezeImageByXpaths
- List of xpaths. Images will be freezed which are passed using xpaths. For this to workfreezeAnimatedImage
must be set to true.percyCSS
- Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.ignoreRegionXpaths
- List of xpaths. elements in the DOM can be ignored using xpathignoreRegionSelectors
- List of selectors. elements in the DOM can be ignored using selectors.ignoreRegionSeleniumElements
- List of selenium web-element. elements can be ignored using selenium_elements.customIgnoreRegions
- List of custom objects. elements can be ignored using custom boundaries- Refer to example -
-
List<HashMap> customRegion = new ArrayList<>(); HashMap<String, Integer> region1 = new HashMap<>(); region1.put("top", 10); region1.put("bottom", 110); region1.put("right", 10); region1.put("left", 120); customRegion.add(region1); options.put("custom_ignore_regions", customRegion);
-
- Parameters:
top
(int): Top coordinate of the ignore region.bottom
(int): Bottom coordinate of the ignore region.left
(int): Left coordinate of the ignore region.right
(int): Right coordinate of the ignore region.
- Refer to example -
considerRegionXpaths
- List of xpaths. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.considerRegionSelectors
- List of selectors. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.considerRegionSeleniumElements
- List of selenium web-element. elements can be considered for diffing and will be ignored by Intelli Ignore using selenium_elements.customConsiderRegions
- List of custom objects. elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries- Refer to example -
-
List<HashMap> customRegion = new ArrayList<>(); HashMap<String, Integer> region2 = new HashMap<>(); region2.put("top", 10); region2.put("bottom", 110); region2.put("right", 10); region2.put("left", 120); customRegion.add(region2); options.put("custom_consider_regions", customRegion);
- Parameters:
top
(int): Top coordinate of the consider region.bottom
(int): Bottom coordinate of the consider region.left
(int): Left coordinate of the consider region.right
(int): Right coordinate of the consider region.
-
- Refer to example -
Note: Automate Percy Token starts with auto
keyword. The command can be triggered using exec
keyword.
$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [java test command]
[percy] Percy has started!
[percy] [Java example] : Starting automate screenshot ...
[percy] Screenshot taken "Java example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!
Refer to docs here: Percy on Automate