Ask the Community
Integrate App Percy with Appium and Cucumber
Learn how to integrate Appium with Java-Cucumber automated tests and App Percy to catch visual differences in mobile apps.
We highly recommend using our BrowserStack SDK for Percy integration.
The Percy Appium SDK ships ready-made Cucumber step definitions in the io.percy.appium.cucumber.PercySteps class. Add this package to the Cucumber glue path to write visual tests in plain Gherkin, without authoring custom Java step code.
Prerequisites
In order to conduct Percy visual testing for Java Appium with Cucumber, you must possess the following dependencies:
- Appium version through v2.4.1
- Node 12+ with npm
- Cucumber Java 7.x
Create new app project on percy dashboard
Sign in to Percy and create a new app type project. After you’ve created the project, you’ll be shown a PERCY_TOKEN environment variable. Percy will use the PERCY_TOKEN to know which organisation and project to upload the screenshots to. You will need this PERCY_TOKEN in next steps.
Set the project token as an environment variable
Run the given command to set PERCY_TOKEN as an environment variable:
Install Percy dependencies
If you’re using Maven, add percy-appium-app and cucumber-java to your project dependencies. The Percy SDK declares Cucumber as a provided dependency, so you supply your own Cucumber version (7.x is recommended):
Set up Cucumber hooks
Pass your AppiumDriver instance to PercySteps from a Cucumber @Before hook, and reset it in an @After hook. The setDriver method also registers the Cucumber wrapper in your Percy build information.
Add the io.percy.appium.cucumber package to the Cucumber glue path so that the step definitions are discovered:
Write a feature file
Use the Percy steps in your Gherkin scenarios. Define device and region options with Given steps before the When screenshot step in the same scenario. The following feature file captures a screenshot on a configured device, and a full page screenshot that ignores a region:
For the full list of available steps, see Available step definitions.
Run your test script
Run your tests using the percy app:exec command as shown below:
If you are unable to use the percy app:exec command or prefer to run your tests using IDE run options, you can use the percy app:exec:start and percy app:exec:stop commands. To learn more, visit Run Percy.
This command starts Percy, creates a new Percy build, takes screenshots and uploads them to your project, and stops Percy:
Summary
You have successfully integrated App Percy with your Appium Cucumber test suite and created your first build. To see the build with snapshots of your application, visit your project in Percy.
When you run another build with visual changes to your application, Percy takes new snapshots. You can then see the comparisons between the two runs on the new build.
Available step definitions
The PercySteps class provides Gherkin steps for screenshots, device configuration, and ignore or consider regions.
Screenshot steps
Capture mobile app screenshots:
| Gherkin step | Description |
|---|---|
When I take a Percy screenshot named "name" |
Basic screenshot |
When I take a Percy screenshot named "name" with full page |
Full page screenshot |
When I take a Percy screenshot named "name" with full screen |
Full screen screenshot |
When I take a Percy screenshot named "name" with options |
Screenshot with all configured options |
Region steps
Define ignore or consider regions before you take a screenshot:
| Gherkin step | Description |
|---|---|
Given I add ignore region XPath "//android.widget.Button[@text='AD']" |
Ignore a region by XPath |
Given I add ignore region accessibility ID "ad-banner" |
Ignore a region by accessibility ID |
Given I add consider region XPath "//android.widget.LinearLayout" |
Consider a region by XPath |
Given I add consider region accessibility ID "main-content" |
Consider a region by accessibility ID |
Given I add custom ignore region 0, 100, 0, 200 |
Ignore a region by coordinates |
Given I add custom consider region 0, 100, 0, 200 |
Consider a region by coordinates |
Given I add ignore region Appium element "elementXPath" |
Ignore an Appium element |
Given I add consider region Appium element "elementXPath" |
Consider an Appium element |
Device and configuration steps
Set device and capture options before you take a screenshot:
| Gherkin step | Description |
|---|---|
Given I set device name "Samsung Galaxy S22" |
Set the device name |
Given I set orientation "portrait" |
Set the orientation, portrait or landscape
|
Given I set status bar height 50 |
Set the status bar height in pixels |
Given I set nav bar height 48 |
Set the navigation bar height in pixels |
Given I set full page to "true" |
Enable or disable full page capture |
Given I set screen lengths 3 |
Set the number of screen lengths to capture |
Given I set labels "smoke,regression" |
Set labels to organize screenshots |
Given I set test case "TC-001" |
Set the test case ID |
Given I set sync to "true" |
Enable sync mode |
Given I set scrollable XPath "//android.widget.ScrollView" |
Set the scrollable element XPath |
Given I set scrollable ID "scrollview" |
Set the scrollable element ID |
Given I set top scrollview offset 100 |
Set the top scroll offset |
Given I set bottom scrollview offset 50 |
Set the bottom scroll offset |
Given I set scroll speed 200 |
Set the scroll speed |
Given I set android scroll area percentage 80 |
Set the Android scroll area percentage |
Given I clear Percy options |
Reset all options to their defaults |
To set a test case execution ID, use the Given I set the test case execution ID "exec-123" step. This step matches the exact phrasing shipped in the SDK.
Related topics
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!