---
id: percy-appium-app
version: "2.0.8"
license: MIT
license_treatment: permissive
maintenance: active
---

# percy-appium-app — Python client for visual testing with Percy for mobile apps

License: permissive · Maintenance: active · Downloads: 283.7K/mo

## What it is and what it does

percy-appium-app is a Python client that connects Appium-driven mobile app tests to Percy's visual testing service. It provides a single function, percy_screenshot(), that captures app screens during test execution and sends them to Percy for baseline comparison and visual regression detection. The package works with both native and hybrid mobile apps, and integrates with Appium-Python-Client and the Percy CLI to manage builds and upload results.

The package is designed for developers running Appium tests who want automated visual regression detection without manually comparing screenshots. It requires the Percy CLI to be installed separately and a Percy project token to function; without the CLI running, screenshots are silently skipped. It supports device-specific metadata, fullpage scrolling capture (alpha), and fine-grained control over which UI regions to ignore or focus on during visual diffing.

Use it for:

- Detect unintended visual changes in mobile app UI across test runs by comparing screenshots against Percy baselines.
- Test responsive layouts and device-specific rendering by capturing screenshots with device name and orientation metadata.
- Ignore dynamic or non-critical UI elements (animations, timestamps, ads) during visual comparison using xpath, selector, or coordinate-based ignore regions.
- Validate fullpage scrollable content in mobile apps by capturing entire scroll areas rather than single viewport screenshots.
- Integrate visual testing into CI/CD pipelines by running Appium tests under 'percy app:exec' to automatically create and track visual builds.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Integrates Percy visual testing into Python Appium tests, capturing and comparing mobile app screenshots against baselines to detect visual regressions.

Yes, with conditions. Install if you are already using Appium for mobile testing and need visual regression detection integrated into your test suite. The low install friction and active maintenance are positive signals. However, the Pre-Alpha status means the API and features may change; start with a non-critical test suite and verify compatibility with your Appium and urllib3 versions before relying on it in production. Requires separate Percy CLI setup and a paid Percy account to upload results.

## Install

pip install percy-appium-app
uv add percy-appium-app
poetry add percy-appium-app

## Installing percy-appium-app

Before you install: Low install friction with a pure-Python wheel distribution. Active maintenance with a recent release 50 days ago; however, the package is classified as Pre-Alpha, suggesting it may still be evolving and not yet production-stable.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions, making it suitable for most commercial and open-source projects.

Quickstart:

pip install percy-appium-app

from appium import webdriver
from percy import percy_screenshot

driver = webdriver.Remote("https://user:key@hub.browserstack.com/wd/hub", caps)
percy_screenshot(driver, 'screenshot_name')

Requires @percy/cli to be installed separately via npm and PERCY_TOKEN environment variable set when running tests via 'percy app:exec' to upload screenshots.

Verify before relying:

- Whether the package works reliably on Python versions beyond 3.9 despite claiming 3.6+ support.
- Current status of the urllib3 compatibility issue mentioned in the description and whether it affects typical installations.
- Whether the alpha-stage fullpage and scrollable element features are production-ready or experimental.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 283.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

appium visual testing, mobile app screenshot comparison, percy python integration, visual regression testing appium, mobile visual testing framework, mobile-testing, visual-regression, appium

[View on SkillFed](https://skillfed.io/packages/percy-appium-app) · [View on PyPI](https://pypi.org/project/percy-appium-app/)