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

Selenium v1

Visual testing with Selenium for Python frameworks

Package Status Build 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!