Integrate Percy with Selenium and Mocha JS
Learn how to integrate Selenium with Mocha JS automated tests and Percy to catch visual differences in your website.
Percy integrates with your tests using both Percy and BrowserStack SDK. To establish this integration, choose the appropriate SDK and refer to the following section accordingly:
To integrate your Mocha JS based test suite with Percy using the BrowserStack SDK, follow these steps:
Prerequisites
Before you start, ensure that you have a BrowserStack Automate account using the BrowserStack SDK to integrate your test script.
Set BrowserStack credentials
Save your BrowserStack credentials as environment variables. It simplifies running your test suite from your local or CI environment. You can export the environment variables for the Username and Access Key of your BrowserStack account or you can set it in the config file.
Install or Upgrade BrowserStack SDK
Update your BrowserStack config file
In the browserstack.yml file:
-
Set
percy: true. -
Set a
projectName.
After you run a test, an Automate project and a Percy project are created with the project name you set here.
If a Percy project by the name you set in thebrowserstack.ymlfile already exists, your screenshots are added to the same project. However, if the name matches an App Percy project, your visual tests will continue to run, but an error message will appear in your logs. Your functional tests still run as expected. -
Set
percyCaptureMode: auto.
There are other supported automated capture modes in thepercyCaptureModeparameter. The table below lists and describes all the acceptable modes.
| Percy screenshot capture mode | Description |
|---|---|
auto |
Automatically capture screenshots on common events such as screenshot, click, and sendKeys. |
testcase |
Automatically capture screenshots at the end of each test case. |
click |
Automatically capture screenshots on every click. |
screenshot |
Automatically capture screenshots on every driver.screenshot call. |
manual |
This gives you more control over the screenshots you want captured. When used, you have to add the PercySDK.screenshot(driver, name) method at required points in your test script. |
Below sample browserstack.yml file shows how to set the percy, the projectName, and the percyCaptureMode parameters.
Additonal configuration settings (Optional)
To manually capture screenshots alongside the auto mode, implement the following steps in your test script:
- Import the BrowserStack Percy SDK in your test script.
- Add the
percy.screenshot(driver, name)method at required points in your test script to get the screenshots you want.
Here’s an example:
Run your test script
Congratulations!
You have successfully integrated Percy with BrowserStack SDK 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 screenshots. You can then see the comparisons between the two runs on the new build. You can access the Percy dashboard directly from the Automate dashboard.
Percy SDK offers Percy with Automate integration for your Mocha tests, choose Automate to run visual tests on a range of desktop, mobile, and browser combinations.
Before you begin, ensure your Automate script’s capabilities are using Selenium version 3.11.0 and above.
- We recommend using Selenium 4 with Percy on Automate to boost performance and ensure increased stability while capturing screenshots.
- Capture a full-page screenshot using the full-page parameter. By default, Percy On Automate captures a single tile, for the full-page screenshot, refer to full page screenshot on Percy with Automate.
Integrate Percy on Automate with your test suite to run visual tests. To do that, follow these steps:
Step 1 - Install the latest Percy CLI
Step 2 - Install the SDK
For Javascript-based frameworks like WebdriverIO, or Mocha
Step 3 - In the Percy dashboard make selections as below:
- Select Web as the platform.
- Select Automate to handle browser selection.
- Click Create Project.
Step 4 - Export the Percy token.
A Percy token is generated when you create a project. Export this token environment variables.
Step 5 - Update your Automate test script.
(1) Import percy_screenshot from Percy library using the below code:
(2) Use the Percy screenshot command to take required screenshots in your Automate session.
For example, in the following Javascript code, the percyScreenshot("name", "options") method is called twice. In the first instance, we are passing only the required argument which is “name”. In the second instance, we are passing both the required and optional “options”.
(3) Add the browser capabilities to your test script
We recommend running your build using a single browser like Chrome or Firefox, to begin with. Once you have achieved stability with Chrome or Firefox, you can set up cross-browser testing.
// Add the following capabilities to your test script
const capabilities = {
'bstack:options': {
os: 'Windows',
osVersion: '10'
},
browserName: 'Chrome',
browserVersion: 'latest'
};
// Add these capabilities to your test script
const capabilities = {
os: 'Windows',
os_version: '10',
browserName: 'Chrome',
browser_version: 'latest'
};
Step 6 - Run the build
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!