An extension library for adding WebDriver Protocol and Appium commands to the Selenium Python language binding for use with the mobile testing framework Appium.

There are three ways to install and use the Appium Python client.

1. Install from PyPi, as 'Appium-Python-Client'.

   pip install Appium-Python-Client

   You can see the history from here

2. Install from source, via PyPi. From 'Appium-Python-Client', download and unarchive the source tarball (Appium-Python-Client-X.X.tar.gz).

   tar -xvf Appium-Python-Client-X.X.tar.gz cd Appium-Python-Client-X.X python setup.py install

3. Install from source via GitHub.

   git clone git@github.com:appium/python-client.git cd python-client python setup.py install

The Appium Python Client depends on Selenium Python binding, thus the Selenium Python binding update might affect the Appium Python Client behavior. For example, some changes in the Selenium binding could break the Appium client.

Note We strongly recommend you manage dependencies with version management tools such as uv to keep compatible version combinations.

• This change affects only for users who specify keep_alive, direct_connection and strict_ssl arguments for webdriver.Remote:
  • Please use AppiumClientConfig as client_config argument similar to how it is specified below:

    SERVER_URL_BASE = 'http://127.0.0.1:4723' # before driver = webdriver.Remote( SERVER_URL_BASE, options=UiAutomator2Options().load_capabilities(desired_caps), direct_connection=True, keep_alive=False, strict_ssl=False ) # after from appium.webdriver.client_config import AppiumClientConfig client_config = AppiumClientConfig( remote_server_addr=SERVER_URL_BASE, direct_connection=True, keep_alive=False, ignore_certificates=True, ) driver = webdriver.Remote( options=UiAutomator2Options().load_capabilities(desired_caps), client_config=client_config )

    • Note that you can keep using webdriver.Remote(url, options=options, client_config=client_config) format as well. In such case the remote_server_addr argument of AppiumClientConfig constructor would have priority over the url argument of webdriver.Remote constructor.
• Use http://127.0.0.1:4723 as the default server url instead of http://127.0.0.1:4444/wd/hub

• Removal
  • MultiAction and TouchAction are removed. Please use W3C WebDriver actions or mobile: extensions
    • appium/webdriver/extensions/action_helpers.py
    • https://www.selenium.dev/documentation/webdriver/actions_api/
    • https://www.youtube.com/watch?v=oAJ7jwMNFVU
    • https://appiumpro.com/editions/30-ios-specific-touch-action-methods
    • https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api
  • Deprecated AppiumBy.WINDOWS_UI_AUTOMATION, which has no usage right now.

• options keyword argument in the webdriver.Remote constructor such as XCUITestOptions instead of desired_capabilities
  • Available options are https://github.com/appium/python-client/tree/master/appium/options
    • Please check the Usage below as an example.
  • Not a "new" change, but the desired_capabilities argument has been removed since v3.
• Replacement
  • start_activity method: Please use mobile: startActivity
  • launch_app, close_app and reset methods: Please refer to appium/appium#15807
  • available_ime_engines, is_ime_active, activate_ime_engine, deactivate_ime_engine and active_ime_engine methods: Please use mobile: shell
  • set_value and set_text methods: Please use element.send_keys or send_keys by W3C Actions
• Removal
  • end_test_coverage method is no longer available
  • session property is no longer available
  • all_sessions property is no longer available

• Enhancement
  • Updated base Selenium Python binding version to v4
    • Removed forceMjsonwp since Selenium v4 and Appium Python client v2 expect only W3C WebDriver protocol
  • Methods ActionHelpers#scroll, ActionHelpers#drag_and_drop, ActionHelpers#tap, ActionHelpers#swipe and ActionHelpers#flick now call W3C actions as its backend
    • Please check each behavior. Their behaviors could slightly differ.
  • Added strict_ssl to relax SSL errors such as self-signed ones
• Deprecated
  • MultiAction and TouchAction are deprecated. Please use W3C WebDriver actions or mobile: extensions
  • launch_app, close_app, and reset are deprecated. Please read issues#15807 for more details

Some elements can be handled with touch pointer action instead of the default mouse pointer action in the Selenium Python client. For example, the below action builder is to replace the default one with the touch pointer action.

from selenium.webdriver import ActionChains from selenium.webdriver.common.actions import interaction from selenium.webdriver.common.actions.action_builder import ActionBuilder from selenium.webdriver.common.actions.pointer_input import PointerInput actions = ActionChains(driver) # override as 'touch' pointer action actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "touch")) actions.w3c_actions.pointer_action.move_to_location(start_x, start_y) actions.w3c_actions.pointer_action.pointer_down() actions.w3c_actions.pointer_action.pause(2) actions.w3c_actions.pointer_action.move_to_location(end_x, end_y) actions.w3c_actions.pointer_action.release() actions.perform()

• appium/webdriver/extensions/action_helpers.py
• https://www.selenium.dev/documentation/webdriver/actions_api/

The Appium Python Client is fully compliant with the WebDriver Protocol including several helpers to make mobile testing in Python easier.

To use the new functionality now, and to use the superset of functions, instead of including the Selenium webdriver module in your test code, use that from Appium instead.

from appium import webdriver

From there much of your test code will work with no change.

As a base for the following code examples, the following set up the UnitTest environment:

# Python/Pytest import pytest from appium import webdriver # Options are only available since client version 2.3.0 # If you use an older client then switch to desired_capabilities # instead: https://github.com/appium/python-client/pull/720 from appium.options.android import UiAutomator2Options from appium.options.ios import XCUITestOptions from appium.webdriver.appium_service import AppiumService from appium.webdriver.common.appiumby import AppiumBy APPIUM_PORT = 4723 APPIUM_HOST = '127.0.0.1' # HINT: fixtures below could be extracted into conftest.py # HINT: and shared across all tests in the suite @pytest.fixture(scope='session') def appium_service(): service = AppiumService() service.start( # Check the output of `appium server --help` for the complete list of # server command line arguments args=['--address', APPIUM_HOST, '-p', str(APPIUM_PORT)], timeout_ms=20000, ) yield service service.stop() def create_ios_driver(custom_opts = None): options = XCUITestOptions() options.platformVersion = '13.4' options.udid = '123456789ABC' if custom_opts is not None: options.load_capabilities(custom_opts) # Appium1 points to http://127.0.0.1:4723/wd/hub by default return webdriver.Remote(f'http://{APPIUM_HOST}:{APPIUM_PORT}', options=options) def create_android_driver(custom_opts = None): options = UiAutomator2Options() options.platformVersion = '10' options.udid = '123456789ABC' if custom_opts is not None: options.load_capabilities(custom_opts) # Appium1 points to http://127.0.0.1:4723/wd/hub by default return webdriver.Remote(f'http://{APPIUM_HOST}:{APPIUM_PORT}', options=options) @pytest.fixture def ios_driver_factory(): return create_ios_driver @pytest.fixture def ios_driver(): # prefer this fixture if there is no need to customize driver options in tests driver = create_ios_driver() yield driver driver.quit() @pytest.fixture def android_driver_factory(): return create_android_driver @pytest.fixture def android_driver(): # prefer this fixture if there is no need to customize driver options in tests driver = create_android_driver() yield driver driver.quit() def test_ios_click(appium_service, ios_driver_factory): # Usage of the context manager ensures the driver session is closed properly # after the test completes. Otherwise, make sure to call `driver.quit()` on teardown. with ios_driver_factory({ 'appium:app': '/path/to/app/UICatalog.app.zip' }) as driver: el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item') el.click() def test_android_click(appium_service, android_driver_factory): # Usage of the context manager ensures the driver session is closed properly # after the test completes. Otherwise, make sure to call `driver.quit()` on teardown. with android_driver_factory({ 'appium:app': '/path/to/app/test-app.apk', 'appium:udid': '567890', }) as driver: el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item') el.click()

Appium Python Client has a common options class named AppiumOptions but the available commands are minimal. It does not have driver/automationName specific commands unless adding commands with add_command method.

Available options for each automation name below will help to check what options are already defined. Please use proper options for your automaiton usage.

If your Selenium/Appium server decorates the new session capabilities response with the following keys:

• directConnectProtocol
• directConnectHost
• directConnectPort
• directConnectPath

Then python client will switch its endpoint to the one specified by the values of those keys.

from appium import webdriver # Options are only available since client version 2.3.0 # If you use an older client then switch to desired_capabilities # instead: https://github.com/appium/python-client/pull/720 from appium.options.ios import XCUITestOptions from appium.webdriver.client_config import AppiumClientConfig # load_capabilities API could be used to # load options mapping stored in a dictionary options = XCUITestOptions().load_capabilities({ 'platformVersion': '13.4', 'deviceName': 'iPhone Simulator', 'app': '/full/path/to/app/UICatalog.app.zip', }) client_config = AppiumClientConfig( remote_server_addr='http://127.0.0.1:4723', direct_connection=True ) driver = webdriver.Remote( # Appium1 points to http://127.0.0.1:4723/wd/hub by default 'http://127.0.0.1:4723', options=options, client_config=client_config )

strict_ssl option allows you to send commands to an invalid certificate host like a self-signed one.

from appium import webdriver # Options are only available since client version 2.3.0 # If you use an older client then switch to desired_capabilities # instead: https://github.com/appium/python-client/pull/720 from appium.options.common import AppiumOptions options = AppiumOptions() options.platform_name = 'mac' options.automation_name = 'safari' # set_capability API allows to provide any custom option # calls to it could be chained options.set_capability('browser_name', 'safari') # Appium1 points to http://127.0.0.1:4723/wd/hub by default driver = webdriver.Remote('http://127.0.0.1:4723', options=options, strict_ssl=False)

Since Appium Python client v4.3.0, we recommend using selenium.webdriver.remote.client_config.ClientConfig instead of giving strict_ssl as an argument of webdriver.Remote below to configure the validation.

from appium import webdriver from selenium.webdriver.remote.client_config import ClientConfig client_config = ClientConfig( remote_server_addr='http://127.0.0.1:4723', ignore_certificates=True ) driver = webdriver.Remote(client_config.remote_server_addr, options=options, client_config=client_config)

The first argument of webdriver.Remote can set an arbitrary command executor for you.

1. Set init arguments for the pool manager Appium Python client uses to manage HTTP requests.

from appium import webdriver from appium.options.ios import XCUITestOptions import urllib3 from appium.webdriver.appium_connection import AppiumConnection # Retry connection error up to 3 times. init_args_for_pool_manage = { 'retries': urllib3.util.retry.Retry(total=3, connect=3, read=False) } appium_executor = AppiumConnection( remote_server_addr='http://127.0.0.1:4723', init_args_for_pool_manage=init_args_for_pool_manage ) options = XCUITestOptions() options.platformVersion = '13.4' options.udid = '123456789ABC' options.app = '/full/path/to/app/UICatalog.app.zip' driver = webdriver.Remote(appium_executor, options=options)

2. Define a subclass of AppiumConnection

from appium import webdriver from appium.options.ios import XCUITestOptions from appium.webdriver.appium_connection import AppiumConnection class CustomAppiumConnection(AppiumConnection): # Can add your own methods for the custom class pass custom_executor = CustomAppiumConnection(remote_server_addr='http://127.0.0.1:4723') options = XCUITestOptions().load_capabilities({ 'platformVersion': '13.4', 'deviceName': 'iPhone Simulator', 'app': '/full/path/to/app/UICatalog.app.zip', }) driver = webdriver.Remote(custom_executor, options=options)

The AppiumConnection can set selenium.webdriver.remote.client_config.ClientConfig as well.

Appium Python Client has 120 seconds read timeout on each HTTP request since the version v4.3.0 because of the corresponding selenium binding version. You have two methods to extend the read timeout.

1. Recommend Configure timeout via appium.webdriver.client_config.AppiumClientConfig or selenium.webdriver.remote.client_config.ClientConfig
   • timeout argument, or
   • init_args_for_pool_manager argument for urllib3.PoolManager
2. Set GLOBAL_DEFAULT_TIMEOUT environment variable
   • This env var will be removed from the selenium binding (issue)

• https://appium.github.io/python-client-sphinx/ is detailed documentation
• functional tests also may help to see concrete examples.

• Code Style: PEP-0008
  • Apply ruff as pre commit hook
  • Run make command for development. See make help output for details
• Docstring style: Google Style

make install-uv exec $SHELL make sync-dev

Running above commands should automatically setup the virtual environment for the project using the default system Python version and put it into the .venv folder under the project root. If you'd like to customize the Python version then run the following command before make sync-dev:

uv venv --python <V>

where <V> is the actual Python version, for example 3.12.

If you want to customize the folder where uv stores the virtual environment by default (e.g. .venv) then add an argument containing the destination folder path to the above command:

uv venv /venv/root/folder

In order to activate the newly created virtual environment you may either source it:

source /venv/root/folder/bin/activate

or add it to PATH:

export "PATH=/venv/root/folder/bin:$PATH"

Run linter and format checks

make check

Address autofixable linter and formatting issues

make fix

make unittest

Run in parallel (2 threads)

make unittest ARGS="-n 2"

uv run pytest test/functional/ios/search_context/find_by_ios_class_chain_tests.py

1. Create simulators named 'iPhone X - 8100' and 'iPhone X - 8101'
2. Run tests

uv run pytest -n 2 test/functional/ios/search_context/find_by_ios_class_chain_tests.py

Follow the below steps.

uv pip install setuptools uv pip install twine # Type the new version number and 'yes' if you can publish it # You can test the command with DRY_RUN DRY_RUN=1 ./release.sh ./release.sh # release

If the pypi was not able to publish with user name and password, please try out -u and -p option by yourself with twine such as twine upload -u <name> -p <pass> dist/Appium-Python-Client-4.1.0.tar.gz.

Apache License v2