Appium Python Client

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

Getting the Appium Python client

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

Install from PyPi, as 'Appium-Python-Client'.
```
pip install Appium-Python-Client
```
You can see the history from here
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
```

Install from source via GitHub.

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

Compatibility Matrix

Appium Python Client	Selenium binding	Python version
`5.1.1`+	`4.26.0`+	3.9+
`4.5.0` - `5.1.0`	`4.26.0` - `4.31.0`	3.9+
`4.3.0` - `4.4.0`	`4.26.0` - `4.31.0`	3.8+
`3.0.0` - `4.2.1`	`4.12.0` - `4.25.0`	3.8+
`2.10.0` - `2.11.1`	`4.1.0` - `4.11.2`	3.7+
`2.2.0` - `2.9.0`	`4.1.0` - `4.9.0`	3.7+
`2.0.0` - `2.1.4`	`4.0.0`	3.7+
`1.0.0` - `1.3.0`	`3.x`	3.7+
`0.52` and below	`3.x`	2.7, 3.4 - 3.7

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.

Quick migration guide from v4 to v5

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

Quick migration guide from v3 to v4

Removal
- MultiAction and TouchAction are removed. Please use W3C WebDriver actions or mobile: extensions
- Deprecated AppiumBy.WINDOWS_UI_AUTOMATION, which has no usage right now.

Quick migration guide from v2 to v3

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 https://github.com/appium/appium/issues/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

Quick migration guide from v1 to v2

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

MultiAction/TouchAction to W3C actions

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()

Usage

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)

appium-python-client

Description