Selenium for Ruby

Integrating Percy with your Selenium Ruby tests


Covered in this doc

Integrating Percy with your Selenium Ruby tests
Installing and importing the percy module
Calling and configuring Percy.snapshot

Gem VersionGem Version TestTest


If you're not ready to integrate Percy, check out our 2-minute Selenium for Ruby tutorial and example app with Percy already added.

Install @percy/cli (currently only available from NPM). This package does the heavy lifting & communication to our API:

npm install --save-dev @percy/cli
yarn add -D @percy/agent

Now install the percy-selenium Ruby package:

$ gem install percy-selenium

Step 1: In order to start creating snapshots from your Selenium tests, you'll need to import the Percy.snapshot function from the percy package into your test.

# At the top of your test file(s) OR the top of your test helper file
require 'percy'

Step 2: You can now incorporate visual tests in your existing suite:

require 'percy'

driver = Selenium::WebDriver.for :firefox ""

# Take a snapshot
Percy.snapshot(driver, 'homepage')


Step 3: Finally, wrap your test runner command in the percy exec command. This will start a local Percy server to receive snapshots from your Ruby Selenium tests. From there the snapshots are processed and uploaded to your Percy dashboard. An example might be: percy exec -- bundle exec rspec.

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

export PERCY_TOKEN=[your-projects-token]
set PERCY_TOKEN=[your-projects-token]

# Powershell

Now you can run percy exec. For example:

percy exec -- bundle exec rspec

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

That's it! Now, whenever you run your tests with Percy, a snapshot of the app in that state will be uploaded to Percy for visual regression testing!


Percy.snapshot(driver, name[, options])

Global configuration

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