percy

library2.0.2pypypi✓ verified 82d ago

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.

testing

pip install percy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PERCY

percy

testingpythonv2.0.2

Install

2.1s avg

Import

—

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 21.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.1s · import 0.000s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from percy import Client

✗ from percy.runner import PercyRunner

Runner

✓ from percy import Runner

Config

✓ from percy import Config

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

percy --version

Debug

Known issues

breakingThe `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`.

affects: >=2.0.0

breakingThe 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.

affects: >=2.0.0

gotchaAll 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.

affects: All versions

Upgrade

Version history

2.0.2latest on PyPI · released Mar 7, 2019

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/percy/python-percy-client ↗

packagehttps://pypi.org/project/percy/ ↗

homepagehttps://percy.io ↗