{"id":14804,"library":"percy-appium-app","title":"Percy Appium Python Client","description":"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.","status":"active","version":"2.0.7","language":"en","source_language":"en","source_url":"https://github.com/percy/percy-appium-python","tags":["visual testing","mobile","appium","percy","automation","quality assurance"],"install":[{"cmd":"pip install percy-appium-app","lang":"bash","label":"Install Python package"},{"cmd":"npm install --save-dev @percy/cli","lang":"bash","label":"Install Percy CLI (Node.js)"}],"dependencies":[{"reason":"Required for Appium interactions and driver management. Compatibility issues noted with versions > 3 and older urllib3.","package":"appium-python-client","optional":false},{"reason":"Specific version range required for compatibility with certain Appium-Python-Client versions (e.g., >=1.26.15,<2 for Appium-Python-Client >=2.9.0).","package":"urllib3","optional":false},{"reason":"Percy's command-line interface (Node.js based) is essential for orchestrating Percy builds and uploading screenshots. Must be installed globally or locally.","package":"@percy/cli","optional":false}],"imports":[{"symbol":"percy_screenshot","correct":"from percy import percy_screenshot"}],"quickstart":{"code":"import os\nfrom appium import webdriver\nfrom percy import percy_screenshot\n\n# Ensure PERCY_TOKEN is set in your environment\n# export PERCY_TOKEN=\"your_percy_project_token\"\n# export BROWSERSTACK_USERNAME=\"your_bs_username\"\n# export BROWSERSTACK_ACCESS_KEY=\"your_bs_access_key\"\n\nPERCY_TOKEN = os.environ.get('PERCY_TOKEN', '')\nBROWSERSTACK_USERNAME = os.environ.get('BROWSERSTACK_USERNAME', '')\nBROWSERSTACK_ACCESS_KEY = os.environ.get('BROWSERSTACK_ACCESS_KEY', '')\n\nif not PERCY_TOKEN:\n    raise ValueError(\"PERCY_TOKEN environment variable is not set.\")\n\ndesired_caps = {\n    'app': 'bs://<app_hash>', # Replace with your app hash or local app path\n    'deviceName': 'Google Pixel 3',\n    'platformName': 'Android',\n    'platformVersion': '9.0',\n    'build': 'Percy Appium Python Build',\n    'name': 'Percy Appium Test',\n    'automationName': 'UiAutomator2'\n}\n\n# For BrowserStack App Automate\nremote_url = f\"https://{BROWSERSTACK_USERNAME}:{BROWSERSTACK_ACCESS_KEY}@hub-cloud.browserstack.com/wd/hub\"\n\ntry:\n    driver = webdriver.Remote(remote_url, desired_caps)\n    # Your test steps here\n    # ... navigate, interact ...\n\n    percy_screenshot(driver, 'My First App Screenshot')\n\n    # Example: Take another screenshot after an action\n    # driver.find_element_by_accessibility_id('someElement').click()\n    # percy_screenshot(driver, 'After Element Click')\n\nfinally:\n    if driver:\n        driver.quit()\n\n# To run this test, you'll typically use the Percy CLI:\n# PERCY_TOKEN=your_token percy app:exec -- python your_test_file.py","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.8"},{"fix":"It is recommended to constrain your `urllib3` dependency to `>=1.26.15,<2` in your `requirements.txt` file to avoid conflicts.","message":"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.","severity":"gotcha","affected_versions":">=2.9.0 (Appium-Python-Client)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the Percy CLI globally using npm: `npm install -g @percy/cli`. Verify installation by running `percy --version`.","cause":"The `@percy/cli` Node.js package is not installed or not in your system's PATH.","error":"percy: command not found"},{"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).","cause":"The `PERCY_TOKEN` environment variable, which authenticates your Percy project, has not been configured.","error":"ValueError: PERCY_TOKEN environment variable is not set."},{"fix":"Add `urllib3>=1.26.15,<2` to your project's `requirements.txt` to ensure compatibility.","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.","error":"urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(...) Read timed out."}],"ecosystem":"pypi"}