Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Selenium for Python

Covered in this doc

Installing Percy for Python with Selenium
Importing the Percy selenium library
Creating a new Percy object with a WebDriver instance as a parameter
Calling and configuring Percy snapshots

Beta release

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

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(
  root_dir=root_static_dir,
  # 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.
  base_url='/assets',
  webdriver=webdriver,
)

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)
percy_runner.initialize_build()

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

percy_runner.finalize_build()

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):
webdriver.get(self.live_server_url)

percy_runner.snapshot()

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

percy_runner.snapshot(name='homepage')

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

Configuration


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().

Troubleshooting


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.


What's next

To add visual testing to your workflow, we recommend setting up your CI service and source code management system.

CI service overview

Selenium for Python


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.