percy-selenium

What it is and what it does

percy-selenium is a Python client that connects Selenium browser automation to Percy's visual testing service. It provides functions like percy_snapshot() and percy_screenshot() that capture the current state of a web page and send it to Percy for comparison against baseline images, flagging visual regressions when they occur.

The package wraps selenium and requests to communicate with Percy's infrastructure. It requires the @percy/cli Node package and a PERCY_TOKEN to function; without them, snapshot calls are no-ops. It supports both standard visual snapshots and Percy on Automate screenshots, with options for full-page capture, animated image freezing, region-based comparison, and selective element ignoring or consideration during diff analysis.

Use it for:

• Detect unintended visual changes in UI components across browser versions or screen sizes
• Validate responsive design by capturing snapshots at different viewport dimensions
• Monitor visual consistency of marketing or public-facing pages after code deployments
• Automate screenshot comparison in CI/CD pipelines to catch layout or styling regressions
• Test visual appearance of dynamically generated content or third-party integrations

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Integrates Percy visual testing into Python Selenium tests, capturing and comparing screenshots against baseline images to detect visual regressions.

Yes, if you are already using Selenium for browser automation and want to add visual regression detection to your test suite. The low install friction, active maintenance, MIT license, and zero known vulnerabilities make it a straightforward addition. You will need to set up @percy/cli and obtain a Percy project token; without those, the package is present but inactive.

Install

percy-selenium on PyPI

pip install percy-selenium

uv add percy-selenium

poetry add percy-selenium

Installing percy-selenium

Before you install

Low install friction with a pure-Python wheel. Actively maintained with a recent release; last commit on 2026-08-10 and production-stable status indicate ongoing support.

License in practice

MIT license permits commercial and private use with minimal restrictions; suitable for most projects without licensing concerns.

Quickstart

pip install percy-selenium

from percy import percy_snapshot
from selenium import webdriver

browser = webdriver.Firefox()
browser.get('http://example.com')
percy_snapshot(browser, 'Python example')

Requires @percy/cli to be installed via npm and PERCY_TOKEN environment variable set to upload snapshots; without these, snapshots are silently disabled.

Verify before relying

• Whether percy-selenium works with all Selenium driver types or only specific ones
• Performance impact of snapshot operations on test execution time
• Compatibility with headless browser modes and remote WebDriver instances

Package facts

Evidence: percy_selenium-2.2.1-py3-none-any.whl

Keywords: selenium, percy, visual, testing

Tags

More Testing packages