Percy Python Client

2.0.2 · active · verified Fri Apr 17

The `percy` library provides a Python client for integrating visual regression testing with Percy (https://percy.io). It enables capturing snapshots of web pages during tests and uploading them to the Percy platform for visual comparison. It is currently at version 2.0.2, with an active development cycle that frequently includes minor improvements and occasional major versions for breaking changes.

Common errors

```
percy: environment variable PERCY_TOKEN missing
```
cause The Percy client cannot authenticate with the Percy API without a valid token.

fix Set the `PERCY_TOKEN` environment variable. You can find your project's token in the Percy dashboard.
```
AttributeError: 'PercyRunner' object has no attribute 'create_build'
```
cause Attempting to call `create_build` method on `PercyRunner` directly after the v2.0.0 breaking change, which significantly altered its interface and made it mostly internal.

fix Instead of `runner.create_build()`, simply use `runner.start_build()`. The build creation is now handled automatically within the `start_build` method based on environment variables.
```
Error: The percy:percy-snapshot command cannot be run because a Percy build is not in progress.
```
cause You tried to call `percy_snapshot` before `runner.start_build()` was successfully executed, or after `runner.finalize_build()` was called.

fix Ensure `runner.start_build()` is called before any `percy_snapshot()` calls and that `runner.finalize_build()` is called only after all snapshots are taken, typically in a `finally` block or test teardown.

Warnings

breaking The `PERCY_PROJECT` environment variable is no longer supported or handled by the client library. It was removed in v2.0.0.
Fix: Remove `PERCY_PROJECT` from your CI environment variables. Percy now determines the project based on the `PERCY_TOKEN`.
breaking The direct interface for `create_build` on `PercyRunner` was changed significantly in v2.0.0. It is now primarily called internally and accepts only optional arguments, with most build metadata inferred from environment variables.
Fix: Avoid direct calls to `create_build`. The recommended approach is to simply call `runner.start_build()` which handles the build creation internally. Ensure necessary environment variables (e.g., `PERCY_TOKEN`) are correctly set.
gotcha All Percy API interactions, including uploading snapshots, require the `PERCY_TOKEN` environment variable to be set. Without it, the client will run but no snapshots will be uploaded.
Fix: Set the `PERCY_TOKEN` environment variable in your CI/CD environment or locally (e.g., `export PERCY_TOKEN="YOUR_TOKEN"`). Obtain your token from the Percy project settings on percy.io.

Install

pip install percy Install stable version

Imports

PercyRunner
```
from percy.runner import PercyRunner
```

percy_snapshot

from percy.snapshot import percy_snapshot

Quickstart

This quickstart demonstrates the basic lifecycle for using the Percy Python client: initialize `PercyRunner`, start a build, take one or more snapshots using a WebDriver instance, and then finalize the build. It requires a `PERCY_TOKEN` environment variable to successfully upload snapshots to Percy. A mock WebDriver is used to make the example runnable without a full browser setup.

import os
from percy.runner import PercyRunner
from percy.snapshot import percy_snapshot

# Percy requires a WebDriver instance (e.g., from Selenium or Playwright).
# For this example, we'll use a mock driver.
class MockWebDriver:
    def __init__(self):
        self.title = "Mock Page Title"
        self.current_url = "http://localhost:8000/mock-page"

    def execute_script(self, script):
        # Simulate returning page HTML or other script results
        if "document.documentElement.outerHTML" in script:
            return "<html><body><h1>Hello from Percy!</h1></body></html>"
        return None

# Ensure PERCY_TOKEN is set in your environment variables for actual uploads.
# Example: export PERCY_TOKEN="YOUR_PERCY_TOKEN"
percy_token = os.environ.get('PERCY_TOKEN', 'YOUR_PERCY_TOKEN_IF_MISSING')
if percy_token == 'YOUR_PERCY_TOKEN_IF_MISSING':
    print("Warning: PERCY_TOKEN environment variable is not set. Snapshots will not be uploaded.")

runner = PercyRunner()
try:
    # Start a Percy build
    runner.start_build()
    print("Percy build started.")

    # Instantiate the mock driver
    driver = MockWebDriver()

    # Take a snapshot
    percy_snapshot(driver, name="Example Snapshot 1", widths=[768, 1280])
    print("Snapshot 'Example Snapshot 1' taken.")

    # You can take multiple snapshots in a single build
    # percy_snapshot(driver, name="Example Snapshot 2", fullscreen=True)

finally:
    # Finalize the Percy build
    runner.finalize_build()
    print("Percy build finalized.")

view raw JSON →