# Appium Python Client
[](https://badge.fury.io/py/Appium-Python-Client)
[](https://pepy.tech/project/appium-python-client)
[](https://github.com/appium/python-client/actions/workflows/functional-test.yml)
An extension library for adding [WebDriver Protocol](https://www.w3.org/TR/webdriver/) and Appium commands to the Selenium Python language binding for use with the mobile testing framework [Appium](https://appium.io).
## Getting the Appium Python client
There are three ways to install and use the Appium Python client.
1. Install from [PyPi](https://pypi.org), as
['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/).
```shell
pip install Appium-Python-Client
```
You can see the history from [here](https://pypi.org/project/Appium-Python-Client/#history)
2. Install from source, via [PyPi](https://pypi.org). From ['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/),
download and unarchive the source tarball (Appium-Python-Client-X.X.tar.gz).
```shell
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](https://github.com/appium/python-client).
```shell
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](https://pypi.org/project/selenium/), 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](https://docs.astral.sh/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:
```python
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
- [appium/webdriver/extensions/action_helpers.py](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.
### 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](#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`](https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#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`](https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#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](https://github.com/appium/appium/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.
```python
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](appium/webdriver/extensions/action_helpers.py)
- https://www.selenium.dev/documentation/webdriver/actions_api/
## 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.
```python
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](https://docs.python.org/3/library/unittest.html)
environment:
```python
# 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()
```
### Available `options`
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.
`automationName` | Package path
|:---|:-----|
any | `appium.options.common.base.AppiumOptions`
`uiautomator2` | `appium.options.android.Uiautomator2Options`
`espresso` | `appium.options.android.EspressoOptions`
`xcuitest` | `appium.options.ios.XCUITestOptions`
`safari` | `appium.options.ios.SafariOptions`
`mac2` | `appium.options.mac.Mac2Options`
`windows` | `appium.options.WindowsOptions`
`gecko` | `appium.options.GeckoOptions`
`flutterintegration` | `appium.options.flutter_integration.FlutterOptions`
## Direct Connect URLs
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.
```python
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
)
```
## Relax SSL validation
`strict_ssl` option allows you to send commands to an invalid certificate host like a self-signed one.
```python
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.
```python
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)
```
## Set custom `AppiumConnection`
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.
```python
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`
```python
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.
## Relaxing HTTP request read timeout
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://github.com/SeleniumHQ/selenium/issues/15604))
## Documentation
- https://appium.github.io/python-client-sphinx/ is detailed documentation
- [functional tests](test/functional) also may help to see concrete examples.
## Development
- Code Style: [PEP-0008](https://www.python.org/dev/peps/pep-0008/)
- Apply `ruff` as pre commit hook
- Run `make` command for development. See `make help` output for details
- Docstring style: [Google Style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
- `gitchangelog` generates `CHANGELOG.rst`
### Setup
```bash
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`:
```bash
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:
```bash
uv venv /venv/root/folder
```
In order to activate the newly created virtual environment you may either source it:
```bash
source /venv/root/folder/bin/activate
```
or add it to PATH:
```bash
export "PATH=/venv/root/folder/bin:$PATH"
```
### Linting And Formatting
Run linter and format checks
```bash
make check
```
Address autofixable linter and formatting issues
```bash
make fix
```
### Testing
#### Unit
```bash
make unittest
```
Run in parallel (2 threads)
```bash
make unittest ARGS="-n 2"
```
#### Functional
```bash
uv run pytest test/functional/ios/search_context/find_by_ios_class_chain_tests.py
```
#### In parallel for iOS
1. Create simulators named 'iPhone X - 8100' and 'iPhone X - 8101'
1. Run tests
```bash
uv run pytest -n 2 test/functional/ios/search_context/find_by_ios_class_chain_tests.py
```
## Release
Follow the below steps.
```bash
uv pip install setuptools
uv pip install twine
uv pip install gitchangelog
# 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`.
## License
Apache License v2
Raw data
{
"_id": null,
"home_page": null,
"name": "Appium-Python-Client",
"maintainer": "Kazuaki Matsuo, Mykola Mokhnach, Mori Atsushi",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "appium, mobile automation, python client, selenium",
"author": null,
"author_email": "Isaac Murchie <isaac@saucelabs.com>",
"download_url": "https://files.pythonhosted.org/packages/c8/08/41c11ee54fe9bc414927649da1358e96d05ff206e43d3dc056b06b4d0809/appium_python_client-5.2.0.tar.gz",
"platform": null,
"description": "# Appium Python Client\n\n[](https://badge.fury.io/py/Appium-Python-Client)\n[](https://pepy.tech/project/appium-python-client)\n\n[](https://github.com/appium/python-client/actions/workflows/functional-test.yml)\n\nAn extension library for adding [WebDriver Protocol](https://www.w3.org/TR/webdriver/) and Appium commands to the Selenium Python language binding for use with the mobile testing framework [Appium](https://appium.io).\n\n## Getting the Appium Python client\n\nThere are three ways to install and use the Appium Python client.\n\n1. Install from [PyPi](https://pypi.org), as\n['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/).\n\n ```shell\n pip install Appium-Python-Client\n ```\n\n You can see the history from [here](https://pypi.org/project/Appium-Python-Client/#history)\n\n2. Install from source, via [PyPi](https://pypi.org). From ['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/),\ndownload and unarchive the source tarball (Appium-Python-Client-X.X.tar.gz).\n\n ```shell\n tar -xvf Appium-Python-Client-X.X.tar.gz\n cd Appium-Python-Client-X.X\n python setup.py install\n ```\n\n3. Install from source via [GitHub](https://github.com/appium/python-client).\n\n ```shell\n git clone git@github.com:appium/python-client.git\n cd python-client\n python setup.py install\n ```\n\n## Compatibility Matrix\n\n|Appium Python Client| Selenium binding| Python version |\n|----|----|----|\n|`5.1.1`+|`4.26.0`+ | 3.9+ |\n|`4.5.0` - `5.1.0`|`4.26.0` - `4.31.0` | 3.9+ |\n|`4.3.0` - `4.4.0`|`4.26.0` - `4.31.0` | 3.8+ |\n|`3.0.0` - `4.2.1` |`4.12.0` - `4.25.0` | 3.8+ |\n|`2.10.0` - `2.11.1` |`4.1.0` - `4.11.2` | 3.7+ |\n|`2.2.0` - `2.9.0` |`4.1.0` - `4.9.0` | 3.7+ |\n|`2.0.0` - `2.1.4` |`4.0.0` | 3.7+ |\n|`1.0.0` - `1.3.0` |`3.x`| 3.7+ |\n|`0.52` and below|`3.x`| 2.7, 3.4 - 3.7 |\n\nThe Appium Python Client depends on [Selenium Python binding](https://pypi.org/project/selenium/), thus\nthe Selenium Python binding update might affect the Appium Python Client behavior.\nFor example, some changes in the Selenium binding could break the Appium client.\n\n> **Note**\n> We strongly recommend you manage dependencies with version management tools such as\n> [uv](https://docs.astral.sh/uv/) to keep compatible version combinations.\n\n\n### Quick migration guide from v4 to v5\n- This change affects only for users who specify `keep_alive`, `direct_connection` and `strict_ssl` arguments for `webdriver.Remote`:\n - Please use `AppiumClientConfig` as `client_config` argument similar to how it is specified below:\n ```python\n SERVER_URL_BASE = 'http://127.0.0.1:4723'\n # before\n driver = webdriver.Remote(\n SERVER_URL_BASE,\n options=UiAutomator2Options().load_capabilities(desired_caps),\n direct_connection=True,\n keep_alive=False,\n strict_ssl=False\n )\n\n # after\n from appium.webdriver.client_config import AppiumClientConfig\n client_config = AppiumClientConfig(\n remote_server_addr=SERVER_URL_BASE,\n direct_connection=True,\n keep_alive=False,\n ignore_certificates=True,\n )\n driver = webdriver.Remote(\n options=UiAutomator2Options().load_capabilities(desired_caps),\n client_config=client_config\n )\n ```\n - Note that you can keep using `webdriver.Remote(url, options=options, client_config=client_config)` format as well.\n In such case the `remote_server_addr` argument of `AppiumClientConfig` constructor would have priority over the `url` argument of `webdriver.Remote` constructor.\n- Use `http://127.0.0.1:4723` as the default server url instead of `http://127.0.0.1:4444/wd/hub`\n\n### Quick migration guide from v3 to v4\n- Removal\n - `MultiAction` and `TouchAction` are removed. Please use W3C WebDriver actions or `mobile:` extensions\n - [appium/webdriver/extensions/action_helpers.py](appium/webdriver/extensions/action_helpers.py)\n - https://www.selenium.dev/documentation/webdriver/actions_api/\n - https://www.youtube.com/watch?v=oAJ7jwMNFVU\n - https://appiumpro.com/editions/30-ios-specific-touch-action-methods\n - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api\n - Deprecated `AppiumBy.WINDOWS_UI_AUTOMATION`, which has no usage right now.\n\n### Quick migration guide from v2 to v3\n- `options` keyword argument in the `webdriver.Remote` constructor such as `XCUITestOptions` instead of `desired_capabilities`\n - Available options are https://github.com/appium/python-client/tree/master/appium/options\n - Please check the [Usage](#usage) below as an example.\n - Not a \"new\" change, but the `desired_capabilities` argument has been removed since v3.\n- Replacement\n - `start_activity` method: Please use [`mobile: startActivity`](https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#mobile-startactivity)\n - `launch_app`, `close_app` and `reset` methods: Please refer to https://github.com/appium/appium/issues/15807\n - `available_ime_engines`, `is_ime_active`, `activate_ime_engine`, `deactivate_ime_engine` and `active_ime_engine` methods: Please use [`mobile: shell`](https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#mobile-shell)\n - `set_value` and `set_text` methods: Please use `element.send_keys` or `send_keys` by W3C Actions\n- Removal\n - `end_test_coverage` method is no longer available\n - `session` property is no longer available\n - `all_sessions` property is no longer available\n\n### Quick migration guide from v1 to v2\n- Enhancement\n - Updated base Selenium Python binding version to v4\n - Removed `forceMjsonwp` since Selenium v4 and Appium Python client v2 expect only W3C WebDriver protocol\n - Methods `ActionHelpers#scroll`, `ActionHelpers#drag_and_drop`, `ActionHelpers#tap`, `ActionHelpers#swipe` and `ActionHelpers#flick` now call W3C actions as its backend\n - Please check each behavior. Their behaviors could slightly differ.\n - Added `strict_ssl` to relax SSL errors such as self-signed ones\n- Deprecated\n - `MultiAction` and `TouchAction` are deprecated. Please use W3C WebDriver actions or `mobile:` extensions\n - `launch_app`, `close_app`, and `reset` are deprecated. Please read [issues#15807](https://github.com/appium/appium/issues/15807) for more details\n\n#### MultiAction/TouchAction to W3C actions\n\nSome elements can be handled with `touch` pointer action instead of the default `mouse` pointer action in the Selenium Python client.\nFor example, the below action builder is to replace the default one with the `touch` pointer action.\n\n```python\nfrom selenium.webdriver import ActionChains\nfrom selenium.webdriver.common.actions import interaction\nfrom selenium.webdriver.common.actions.action_builder import ActionBuilder\nfrom selenium.webdriver.common.actions.pointer_input import PointerInput\n\nactions = ActionChains(driver)\n# override as 'touch' pointer action\nactions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, \"touch\"))\nactions.w3c_actions.pointer_action.move_to_location(start_x, start_y)\nactions.w3c_actions.pointer_action.pointer_down()\nactions.w3c_actions.pointer_action.pause(2)\nactions.w3c_actions.pointer_action.move_to_location(end_x, end_y)\nactions.w3c_actions.pointer_action.release()\nactions.perform()\n```\n\n- [appium/webdriver/extensions/action_helpers.py](appium/webdriver/extensions/action_helpers.py)\n- https://www.selenium.dev/documentation/webdriver/actions_api/\n\n## Usage\n\nThe Appium Python Client is fully compliant with the WebDriver Protocol\nincluding several helpers to make mobile testing in Python easier.\n\nTo use the new functionality now, and to use the superset of functions, instead of\nincluding the Selenium `webdriver` module in your test code, use that from\nAppium instead.\n\n```python\nfrom appium import webdriver\n```\n\nFrom there much of your test code will work with no change.\n\nAs a base for the following code examples, the following set up the [UnitTest](https://docs.python.org/3/library/unittest.html)\nenvironment:\n\n```python\n# Python/Pytest\nimport pytest\n\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.android import UiAutomator2Options\nfrom appium.options.ios import XCUITestOptions\nfrom appium.webdriver.appium_service import AppiumService\nfrom appium.webdriver.common.appiumby import AppiumBy\n\nAPPIUM_PORT = 4723\nAPPIUM_HOST = '127.0.0.1'\n\n\n# HINT: fixtures below could be extracted into conftest.py\n# HINT: and shared across all tests in the suite\n@pytest.fixture(scope='session')\ndef appium_service():\n service = AppiumService()\n service.start(\n # Check the output of `appium server --help` for the complete list of\n # server command line arguments\n args=['--address', APPIUM_HOST, '-p', str(APPIUM_PORT)],\n timeout_ms=20000,\n )\n yield service\n service.stop()\n\n\ndef create_ios_driver(custom_opts = None):\n options = XCUITestOptions()\n options.platformVersion = '13.4'\n options.udid = '123456789ABC'\n if custom_opts is not None:\n options.load_capabilities(custom_opts)\n # Appium1 points to http://127.0.0.1:4723/wd/hub by default\n return webdriver.Remote(f'http://{APPIUM_HOST}:{APPIUM_PORT}', options=options)\n\n\ndef create_android_driver(custom_opts = None):\n options = UiAutomator2Options()\n options.platformVersion = '10'\n options.udid = '123456789ABC'\n if custom_opts is not None:\n options.load_capabilities(custom_opts)\n # Appium1 points to http://127.0.0.1:4723/wd/hub by default\n return webdriver.Remote(f'http://{APPIUM_HOST}:{APPIUM_PORT}', options=options)\n\n\n@pytest.fixture\ndef ios_driver_factory():\n return create_ios_driver\n\n\n@pytest.fixture\ndef ios_driver():\n # prefer this fixture if there is no need to customize driver options in tests\n driver = create_ios_driver()\n yield driver\n driver.quit()\n\n\n@pytest.fixture\ndef android_driver_factory():\n return create_android_driver\n\n\n@pytest.fixture\ndef android_driver():\n # prefer this fixture if there is no need to customize driver options in tests\n driver = create_android_driver()\n yield driver\n driver.quit()\n\n\ndef test_ios_click(appium_service, ios_driver_factory):\n # Usage of the context manager ensures the driver session is closed properly\n # after the test completes. Otherwise, make sure to call `driver.quit()` on teardown.\n with ios_driver_factory({\n 'appium:app': '/path/to/app/UICatalog.app.zip'\n }) as driver:\n el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item')\n el.click()\n\n\ndef test_android_click(appium_service, android_driver_factory):\n # Usage of the context manager ensures the driver session is closed properly\n # after the test completes. Otherwise, make sure to call `driver.quit()` on teardown.\n with android_driver_factory({\n 'appium:app': '/path/to/app/test-app.apk',\n 'appium:udid': '567890',\n }) as driver:\n el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item')\n el.click()\n```\n\n### Available `options`\n\nAppium Python Client has a common options class named `AppiumOptions` but the available commands are minimal.\nIt does not have driver/automationName specific commands unless adding commands with `add_command` method.\n\nAvailable options for each automation name below will help to check what options are already defined.\nPlease use proper options for your automaiton usage.\n\n`automationName` | Package path\n|:---|:-----|\nany | `appium.options.common.base.AppiumOptions`\n`uiautomator2` | `appium.options.android.Uiautomator2Options`\n`espresso` | `appium.options.android.EspressoOptions`\n`xcuitest` | `appium.options.ios.XCUITestOptions`\n`safari` | `appium.options.ios.SafariOptions`\n`mac2` | `appium.options.mac.Mac2Options`\n`windows` | `appium.options.WindowsOptions`\n`gecko` | `appium.options.GeckoOptions`\n`flutterintegration` | `appium.options.flutter_integration.FlutterOptions`\n\n## Direct Connect URLs\n\nIf your Selenium/Appium server decorates the new session capabilities response with the following keys:\n\n- `directConnectProtocol`\n- `directConnectHost`\n- `directConnectPort`\n- `directConnectPath`\n\nThen python client will switch its endpoint to the one specified by the values of those keys.\n\n```python\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.ios import XCUITestOptions\nfrom appium.webdriver.client_config import AppiumClientConfig\n\n# load_capabilities API could be used to\n# load options mapping stored in a dictionary\noptions = XCUITestOptions().load_capabilities({\n 'platformVersion': '13.4',\n 'deviceName': 'iPhone Simulator',\n 'app': '/full/path/to/app/UICatalog.app.zip',\n})\n\nclient_config = AppiumClientConfig(\n remote_server_addr='http://127.0.0.1:4723',\n direct_connection=True\n)\n\ndriver = webdriver.Remote(\n # Appium1 points to http://127.0.0.1:4723/wd/hub by default\n 'http://127.0.0.1:4723',\n options=options,\n client_config=client_config\n)\n```\n\n## Relax SSL validation\n\n`strict_ssl` option allows you to send commands to an invalid certificate host like a self-signed one.\n\n```python\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.common import AppiumOptions\n\noptions = AppiumOptions()\noptions.platform_name = 'mac'\noptions.automation_name = 'safari'\n# set_capability API allows to provide any custom option\n# calls to it could be chained\noptions.set_capability('browser_name', 'safari')\n\n# Appium1 points to http://127.0.0.1:4723/wd/hub by default\ndriver = webdriver.Remote('http://127.0.0.1:4723', options=options, strict_ssl=False)\n```\n\nSince Appium Python client v4.3.0, we recommend using `selenium.webdriver.remote.client_config.ClientConfig`\ninstead of giving `strict_ssl` as an argument of `webdriver.Remote` below to configure the validation.\n\n```python\nfrom appium import webdriver\n\nfrom selenium.webdriver.remote.client_config import ClientConfig\n\nclient_config = ClientConfig(\n remote_server_addr='http://127.0.0.1:4723',\n ignore_certificates=True\n)\ndriver = webdriver.Remote(client_config.remote_server_addr, options=options, client_config=client_config)\n```\n\n## Set custom `AppiumConnection`\n\nThe first argument of `webdriver.Remote` can set an arbitrary command executor for you.\n\n1. Set init arguments for the pool manager Appium Python client uses to manage HTTP requests.\n\n```python\nfrom appium import webdriver\nfrom appium.options.ios import XCUITestOptions\n\nimport urllib3\nfrom appium.webdriver.appium_connection import AppiumConnection\n\n# Retry connection error up to 3 times.\ninit_args_for_pool_manage = {\n 'retries': urllib3.util.retry.Retry(total=3, connect=3, read=False)\n}\nappium_executor = AppiumConnection(\n remote_server_addr='http://127.0.0.1:4723',\n init_args_for_pool_manage=init_args_for_pool_manage\n)\n\noptions = XCUITestOptions()\noptions.platformVersion = '13.4'\noptions.udid = '123456789ABC'\noptions.app = '/full/path/to/app/UICatalog.app.zip'\ndriver = webdriver.Remote(appium_executor, options=options)\n```\n\n\n2. Define a subclass of `AppiumConnection`\n\n```python\nfrom appium import webdriver\nfrom appium.options.ios import XCUITestOptions\n\nfrom appium.webdriver.appium_connection import AppiumConnection\n\nclass CustomAppiumConnection(AppiumConnection):\n # Can add your own methods for the custom class\n pass\n\ncustom_executor = CustomAppiumConnection(remote_server_addr='http://127.0.0.1:4723')\n\noptions = XCUITestOptions().load_capabilities({\n 'platformVersion': '13.4',\n 'deviceName': 'iPhone Simulator',\n 'app': '/full/path/to/app/UICatalog.app.zip',\n})\ndriver = webdriver.Remote(custom_executor, options=options)\n\n```\n\nThe `AppiumConnection` can set `selenium.webdriver.remote.client_config.ClientConfig` as well.\n\n## Relaxing HTTP request read timeout\n\nAppium Python Client has `120` seconds read timeout on each HTTP request since the version v4.3.0 because of\nthe corresponding selenium binding version.\nYou have two methods to extend the read timeout.\n\n1. **Recommend** Configure timeout via `appium.webdriver.client_config.AppiumClientConfig` or `selenium.webdriver.remote.client_config.ClientConfig`\n - `timeout` argument, or\n - `init_args_for_pool_manager` argument for `urllib3.PoolManager`\n2. Set `GLOBAL_DEFAULT_TIMEOUT` environment variable\n - This env var will be removed from the selenium binding ([issue](https://github.com/SeleniumHQ/selenium/issues/15604))\n\n## Documentation\n\n- https://appium.github.io/python-client-sphinx/ is detailed documentation\n- [functional tests](test/functional) also may help to see concrete examples.\n\n## Development\n\n- Code Style: [PEP-0008](https://www.python.org/dev/peps/pep-0008/)\n - Apply `ruff` as pre commit hook\n - Run `make` command for development. See `make help` output for details\n- Docstring style: [Google Style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)\n- `gitchangelog` generates `CHANGELOG.rst`\n\n### Setup\n\n```bash\nmake install-uv\nexec $SHELL\nmake sync-dev\n```\n\nRunning above commands should automatically setup the virtual environment for the project\nusing the default system Python version and put it into the `.venv` folder under the project root.\nIf you'd like to customize the Python version then run the following command before `make sync-dev`:\n\n```bash\nuv venv --python <V>\n```\n\nwhere `<V>` is the actual Python version, for example `3.12`.\n\nIf you want to customize the folder where uv stores the virtual environment by default\n(e.g. `.venv`) then add an argument containing the destination folder path to the above command:\n\n```bash\nuv venv /venv/root/folder\n```\n\nIn order to activate the newly created virtual environment you may either source it:\n\n```bash\nsource /venv/root/folder/bin/activate\n```\n\nor add it to PATH:\n\n```bash\nexport \"PATH=/venv/root/folder/bin:$PATH\"\n```\n\n### Linting And Formatting\n\nRun linter and format checks\n\n```bash\nmake check\n```\n\nAddress autofixable linter and formatting issues\n\n```bash\nmake fix\n```\n\n### Testing\n\n#### Unit\n\n```bash\nmake unittest\n```\n\nRun in parallel (2 threads)\n\n```bash\nmake unittest ARGS=\"-n 2\"\n```\n\n#### Functional\n\n```bash\nuv run pytest test/functional/ios/search_context/find_by_ios_class_chain_tests.py\n```\n\n#### In parallel for iOS\n\n1. Create simulators named 'iPhone X - 8100' and 'iPhone X - 8101'\n1. Run tests\n\n```bash\nuv run pytest -n 2 test/functional/ios/search_context/find_by_ios_class_chain_tests.py\n```\n\n## Release\n\nFollow the below steps.\n\n```bash\nuv pip install setuptools\nuv pip install twine\nuv pip install gitchangelog\n# Type the new version number and 'yes' if you can publish it\n# You can test the command with DRY_RUN\nDRY_RUN=1 ./release.sh\n./release.sh # release\n```\n\nIf 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`.\n\n## License\n\nApache License v2\n",
"bugtrack_url": null,
"license": null,
"summary": "Python client for Appium",
"version": "5.2.0",
"project_urls": {
"Changelog": "https://github.com/appium/python-client/blob/master/CHANGELOG.rst",
"Homepage": "http://appium.io/",
"Issues": "https://github.com/appium/python-client/issues",
"Repository": "https://github.com/appium/python-client"
},
"split_keywords": [
"appium",
" mobile automation",
" python client",
" selenium"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15fea7d553a49b10d695f8bd0deb093044b24abbe71d141590f0ee32bbc83db9",
"md5": "1bb2f728d75cdb899d8a86fc07d0891b",
"sha256": "518d276ae15403af27b7cf94e25474ed9af475826dcfc400fce3e38f8eb18af3"
},
"downloads": -1,
"filename": "appium_python_client-5.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1bb2f728d75cdb899d8a86fc07d0891b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 348489,
"upload_time": "2025-08-07T14:31:39",
"upload_time_iso_8601": "2025-08-07T14:31:39.971019Z",
"url": "https://files.pythonhosted.org/packages/15/fe/a7d553a49b10d695f8bd0deb093044b24abbe71d141590f0ee32bbc83db9/appium_python_client-5.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c80841c11ee54fe9bc414927649da1358e96d05ff206e43d3dc056b06b4d0809",
"md5": "5cbf7e4b5f124da4a13a27e67e9b10da",
"sha256": "8a84fca6190ff3cf5c35727ddfc3558a5b7eee6a69cbf6b07c3ff6249bc3862f"
},
"downloads": -1,
"filename": "appium_python_client-5.2.0.tar.gz",
"has_sig": false,
"md5_digest": "5cbf7e4b5f124da4a13a27e67e9b10da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 179359,
"upload_time": "2025-08-07T14:31:41",
"upload_time_iso_8601": "2025-08-07T14:31:41.225194Z",
"url": "https://files.pythonhosted.org/packages/c8/08/41c11ee54fe9bc414927649da1358e96d05ff206e43d3dc056b06b4d0809/appium_python_client-5.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 14:31:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "appium",
"github_project": "python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "appium-python-client"
}
JSON
