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