• Stars
    star
    1,669
  • Rank 28,006 (Top 0.6 %)
  • Language
    Python
  • License
    Apache License 2.0
  • Created over 10 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Python language bindings for Appium

Appium Python Client

PyPI version Downloads

Build Status

Code style: black

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

Notice

Since v1.0.0, only Python 3.7+ is supported.

Since v2.0.0, the base selenium client version is v4. The version only works in W3C WebDriver protocol format. If you would like to use the old protocol (MJSONWP), please use v1 Appium Python client.

Quick migration guide from v1 to v2

MultiAction/TouchAction to W3C actions

On UIA2, some elements can be handled with touch pointer action insead of the default mouse pointer action in the Selenium Python cleint. For example, the below action builder is to replace the default one with the touch pointer action.

from selenium.webdriver.common.actions import interaction
from selenium.webdriver.common.actions.action_builder import ActionBuilder

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

Getting the Appium Python client

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 [email protected]:appium/python-client.git
    cd python-client
    python setup.py install

Compatibility Matrix

Appium Python Client Selenium binding
2.10.0+ 4.1.0+
2.2.0 - 2.9.0 4.1.0 - 4.9.0
2.0.0 - 2.1.4 4.0.0
1.1.0 and below 3.x

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

Note We strongly recommend you to manage dependencies with version management tools such as Pipenv and requirements.txt to keep compatible version combinations.

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

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.

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

# 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',
})

driver = webdriver.Remote(
    # Appium1 points to http://127.0.0.1:4723/wd/hub by default
    'http://127.0.0.1:4723',
    options=options,
    direct_connection=True
)

Relax SSL validation

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)

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.
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)
  1. 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)

Documentation

Development

  • Code Style: PEP-0008
    • Apply black, isort and mypy as pre commit hook
    • Run make command for development. See make help output for details
  • Docstring style: Google Style
  • gitchangelog generates CHANGELOG.rst

Setup

  • pip install --user pipenv
  • python -m pipenv lock --clear
    • If you experience Locking Failed! unknown locale: UTF-8 error, then refer pypa/pipenv#187 to solve it.
  • python -m pipenv install --dev --system
  • pre-commit install

Run tests

You can run all of tests running on CI via tox in your local.

$ tox

You also can run particular tests like below.

Unit

$ pytest test/unit

Run with pytest-xdist

$ pytest -n 2 test/unit

Functional

$ 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'
  2. Install test libraries via pip, pip install pytest pytest-xdist
  3. Run tests
$ pytest -n 2 test/functional/ios/search_context/find_by_ios_class_chain_tests.py

Release

Follow below steps.

$ pip install twine
$ pip install git+git://github.com/vaab/gitchangelog.git # Getting via GitHub repository is necessary for Python 3.7
# 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

License

Apache License v2

More Repositories

1

appium

Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol
JavaScript
18,666
star
2

appium-desktop

Appium Server in Desktop GUIs for Mac, Windows, and Linux
JavaScript
4,709
star
3

java-client

Java language binding for writing Appium Tests, conforms to W3C WebDriver Protocol
Java
1,203
star
4

appium-inspector

A GUI inspector for mobile apps and more, powered by a (separately installed) Appium server
JavaScript
1,125
star
5

appium-xcuitest-driver

Appium iOS driver, backed by Apple XCTest
JavaScript
736
star
6

appium-docker-android

Appium Server setup to automate android testing on real devices
Shell
585
star
7

appium-uiautomator2-driver

Appium driver for Android UIAutomator2
JavaScript
558
star
8

appium-flutter-driver

Appium Flutter Driver is a test automation tool for Flutter apps on multiple platforms/OSes. Appium Flutter Driver is part of the Appium mobile test automation tool maintained by community
TypeScript
451
star
9

dotnet-client

Extension to the official Selenium dotnet webdriver
C#
381
star
10

appium-uiautomator2-server

Appium UiAutomator/UiObject2-based server for Android UI automation. This module is used by appium-uiautomator2-driver component
Java
326
star
11

appium-adb

Wrapper around adb used by appium + helper libs
JavaScript
273
star
12

appium-android-driver

Common methods collection used by Android drivers
JavaScript
249
star
13

android-apidemos

A fork of Google's Android ApiDemos application, used for testing Appium
Java
235
star
14

ruby_lib

πŸ’Ž Ruby library for Appium
Ruby
216
star
15

appium-for-mac

[deprecated] Application for automating a mac app with JSON wire protocol
Objective-C
193
star
16

appium-espresso-driver

Espresso integration for Appium
Kotlin
189
star
17

appium-doctor

[Deprecated] Please use https://github.com/appium/appium/tree/master/packages/doctor
JavaScript
128
star
18

appium-ios-device

Tools for interacting with iOS devices
JavaScript
126
star
19

appium-mac2-driver

Next-gen Appium macOS driver, backed by Apple XCTest
Objective-C
124
star
20

io.appium.settings

App for dealing with Android settings
Java
121
star
21

appium-ios-simulator

Module for interacting with iOS simulators
JavaScript
97
star
22

appium-base-driver

Base class for an Appium driver
JavaScript
82
star
23

appium-idb

idb integration for Appium
JavaScript
75
star
24

ios-uicatalog

Apple UICatalog App
Objective-C
73
star
25

appium-chromedriver

Node.js wrapper around Chromedriver
JavaScript
66
star
26

mitmproxy-java

A bridge between Python's mitmproxy and Java programs. Built on top of mitmproxy-node
Java
64
star
27

node-simctl

Node wrapper around Apple's simctl binary
JavaScript
63
star
28

ruby_console

🎁 Appium Ruby Console
Ruby
45
star
29

appium-remote-debugger

Module for dealing with Remote Debugger protocol
JavaScript
44
star
30

appium_capybara

Gem enabling appium support in capybara
Ruby
40
star
31

appium-mac-driver

[deprecated] Mac application driver for Appium
JavaScript
36
star
32

ios-test-app

iOS app for testing
Objective-C
35
star
33

ruby_lib_core

Core library for the Ruby client
Ruby
34
star
34

selenium-swift

selenium bindings for the swift programming language
Swift
33
star
35

node-teen_process

A slightly more grown-up version of Node's child_process
JavaScript
27
star
36

node-adb-client

A direct-to-device ADB client implementation in Node
JavaScript
27
star
37

appium-safari-driver

Safari browser support for Appium
JavaScript
24
star
38

appium.io

[deprecated] The public front-end for Appium
CSS
21
star
39

appium-support

Support libs used across appium packages.
JavaScript
17
star
40

appium-chromium-driver

An Appium driver for the Chrome browser
JavaScript
17
star
41

appium-xcode

Xcode related utilities. Get version number and path to executable.
JavaScript
16
star
42

appium-geckodriver

Support for Geckodriver (Firefox driver) within Appium
JavaScript
15
star
43

sample-apps

Sample app manager, for testing
JavaScript
14
star
44

VodQAReactNative

Sample react native app demoing components and gestures
JavaScript
10
star
45

screenshooter

Screenshot application for Android
Java
10
star
46

appium-fake-driver

A fake Appium driver used for testing and demonstration
JavaScript
8
star
47

droiddriver_examples

Java
6
star
48

DynamicApp

Titanium app generating random code + command injector.
JavaScript
6
star
49

appium-gulp-plugins

Custom plugins used across appium modules
JavaScript
5
star
50

dump2json

Converts UIAutomator XML dump to JSON for Appium.
Java
5
star
51

io.appium.gappium.sampleapp

Appium Sample App for Cordova Test Automation (Gappium)
JavaScript
5
star
52

appium-test-support

A collection of test utility lib used across Appium packages
JavaScript
4
star
53

appium-build-store

Temporary store for Appium builds, for sub-package CI systems
4
star
54

gps-demo-app

Android GPS demo from http://www.impressive-artworx.de/tutorials/android/gps_tutorial_1.zip
Java
4
star
55

appium-event-parser

Node CLI script to help parse event timing output from Appium scripts
JavaScript
4
star
56

appium-gui-libs

Code shared between various Appium GUI projects (Appium Desktop Server, Appium Inspector)
JavaScript
4
star
57

perl-client

Perl
3
star
58

workshop

To be used when people do Appium workshops
JavaScript
3
star
59

clean_apk

APK used to clean up between tests for Appium.
Java
3
star
60

eslint-config-appium

Shared configuration for ESLint
JavaScript
3
star
61

python-client-sphinx

Docs repo for Appium Python Client
3
star
62

worms

Issue tracker for Apple bugs affecting Appium
2
star
63

appium-ios

iOS-specific packages for Appium
JavaScript
2
star
64

ios-webview-app

Webview app for testing appium
Objective-C
2
star
65

blog

A GH powered Appium blog
1
star
66

dmg-template

dmg template for building appium-dot-app
Objective-C
1
star
67

appium.github.com

Appium.io
JavaScript
1
star
68

ios

Appium mono repo containing iOS specific packages.
1
star
69

appium_thor

Appium Thor helpers for appium's gems
Ruby
1
star
70

appiumlogs

Logs from the #appium IRC channel on freenode.net
Shell
1
star
71

packweb

Tools for maintaining projects with large numbers of packages
JavaScript
1
star
72

appium-package-master

A set of tools to create and manage appium packages.
JavaScript
1
star
73

jobs

Appium job board
1
star
74

test_runner

Ruby test runner for Appium
Ruby
1
star
75

appium-benchmarks

A suite of exercises designed to evaluate the performance of an Appium server or service
TypeScript
1
star