Percy Appium Python Client

2.0.7 · active · verified Thu Apr 16

Percy Appium Python Client enables visual testing for mobile applications by integrating with Appium. It provides a function to take screenshots within your Appium tests and upload them to Percy for visual regression analysis. The library is actively maintained, with the latest stable version 2.0.7, and receives regular updates to support newer Appium and Python client versions.

Common errors

```
percy: command not found
```
cause The `@percy/cli` Node.js package is not installed or not in your system's PATH.

fix Install the Percy CLI globally using npm: `npm install -g @percy/cli`. Verify installation by running `percy --version`.
```
ValueError: PERCY_TOKEN environment variable is not set.
```
cause The `PERCY_TOKEN` environment variable, which authenticates your Percy project, has not been configured.

fix Set the `PERCY_TOKEN` environment variable before running your tests. Example: `export PERCY_TOKEN="<your_project_token>"` (Linux/macOS) or `set PERCY_TOKEN="<your_project_token>"` (Windows Command Prompt).
```
urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(...) Read timed out.
```
cause This often occurs due to incompatible versions of `Appium-Python-Client` and `urllib3`, particularly with `Appium-Python-Client >= 2.9.0` and newer `urllib3` versions.

fix Add `urllib3>=1.26.15,<2` to your project's `requirements.txt` to ensure compatibility.

Warnings

breaking The `percy-appium-app` library (v2.0.8-beta.0 and later) introduced fixes for `remote_url` fetching when using `AppiumPythonClient` versions greater than 3. Older versions of `percy-appium-app` might not be compatible, leading to issues with Percy snapshots.
Fix: Upgrade `percy-appium-app` to version `2.0.8-beta.0` or higher to ensure compatibility with `AppiumPythonClient > 3`. Always review changelogs for specific `Appium-Python-Client` version requirements.
gotcha When using `Appium-Python-Client >= v2.9.0`, there can be compatibility issues with recent `urllib3` versions. This can manifest as connection errors or unexpected behavior during driver initialization.
Fix: It is recommended to constrain your `urllib3` dependency to `>=1.26.15,<2` in your `requirements.txt` file to avoid conflicts.
gotcha The `@percy/cli` (Node.js package) is a mandatory dependency for `percy-appium-app` to function correctly. Without it, the `percy app:exec` command will not be available, and Percy builds cannot be created or snapshots uploaded.
Fix: Ensure `@percy/cli` is installed globally (`npm install -g @percy/cli`) or as a dev dependency in your project (`npm install --save-dev @percy/cli`) and accessible in your system's PATH.

Install

pip install percy-appium-app Install Python package
npm install --save-dev @percy/cli Install Percy CLI (Node.js)

Imports

percy_screenshot
```
from percy import percy_screenshot
```

Quickstart

This quickstart demonstrates how to initialize an Appium driver and use `percy_screenshot` to capture visual snapshots. It assumes you have Appium and Percy CLI set up, and environment variables for Percy token and (optionally) BrowserStack credentials. Replace `<app_hash>` with your mobile application's identifier. The test should be executed via the `percy app:exec` command, which manages the Percy build lifecycle.

import os
from appium import webdriver
from percy import percy_screenshot

# Ensure PERCY_TOKEN is set in your environment
# export PERCY_TOKEN="your_percy_project_token"
# export BROWSERSTACK_USERNAME="your_bs_username"
# export BROWSERSTACK_ACCESS_KEY="your_bs_access_key"

PERCY_TOKEN = os.environ.get('PERCY_TOKEN', '')
BROWSERSTACK_USERNAME = os.environ.get('BROWSERSTACK_USERNAME', '')
BROWSERSTACK_ACCESS_KEY = os.environ.get('BROWSERSTACK_ACCESS_KEY', '')

if not PERCY_TOKEN:
    raise ValueError("PERCY_TOKEN environment variable is not set.")

desired_caps = {
    'app': 'bs://<app_hash>', # Replace with your app hash or local app path
    'deviceName': 'Google Pixel 3',
    'platformName': 'Android',
    'platformVersion': '9.0',
    'build': 'Percy Appium Python Build',
    'name': 'Percy Appium Test',
    'automationName': 'UiAutomator2'
}

# For BrowserStack App Automate
remote_url = f"https://{BROWSERSTACK_USERNAME}:{BROWSERSTACK_ACCESS_KEY}@hub-cloud.browserstack.com/wd/hub"

try:
    driver = webdriver.Remote(remote_url, desired_caps)
    # Your test steps here
    # ... navigate, interact ...

    percy_screenshot(driver, 'My First App Screenshot')

    # Example: Take another screenshot after an action
    # driver.find_element_by_accessibility_id('someElement').click()
    # percy_screenshot(driver, 'After Element Click')

finally:
    if driver:
        driver.quit()

# To run this test, you'll typically use the Percy CLI:
# PERCY_TOKEN=your_token percy app:exec -- python your_test_file.py

view raw JSON →