Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2!

Selenium v1

Visual testing with Selenium for Python frameworks

Package StatusPackage Status Build StatusBuild Status

Python client library for visual regression testing with Percy and Selenium tests.

This library is in beta---we welcome contributions to improve it.



Make sure you have completed Setup of your CI service first. You can also test Percy in your local development environment.

Requires Python >= 2.7.

$ pip install percy


The following assumes that webdriver is a Selenium webdriver object of some sort (like webdriver.Chrome()). Proper setup and teardown of Selenium tests is not included here.

First, create a ResourceLoader object. This is the configuration for how Percy will discover your app's assets.

import percy

# Build a ResourceLoader that knows how to collect assets for this application.
root_static_dir = os.path.join(os.path.dirname(__file__), 'static')
loader = percy.ResourceLoader(
  # Prepend `/assets` to all of the files in the static directory, to match production assets.
  # This is only needed if your static assets are served from a nested directory.

Now, create a percy.Runner object and initialize a build. This must be done at the beginning of your entire test suite.

percy_runner = percy.Runner(loader=loader)

Then, at the end of your entire test suite, finalize the build (this needs to be run even if tests fail):



During Selenium tests, use percy_runner.snapshot() in any test to capture the DOM state and send it to Percy for rendering and visual regression testing.

# In a Selenium test, you might visit a page like this (this also assumes we're subclassing
# Django's LiveServerTestCase):


snapshot also accepts a name to uniquely identify it across builds:


Done! Now commit and push your branch to run your tests in your CI service, or create a GitHub PR.

Responsive testing

Setup default responsive breakpoints for all snapshots:

percy_config = percy.Config(default_widths=[1280, 375])
percy_runner = percy.Runner(loader=loader, config=percy_config)

These are the default responsive widths to be used on every snapshot. They can be overridden on a per-snapshot basis by passing the widths arg to snapshot().


To temporarily disable Percy in CI, set the PERCY_ENABLE=0 environment variable.

See Percy usage in the Sentry repository for a complete example of Percy integrated in a large Django application and with pytestintegration.


  1. Fork it ( https://github.com/percy/python-percy-client/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Throw a ★ on it!