An extension library for adding Selenium 3.0 draft and Mobile JSON Wire Protocol Specification draft functionality to the Python language bindings, for use with the mobile testing framework Appium.
There are three ways to install and use the Appium Python client.
-
Install from PyPi, as 'Appium-Python-Client'.
pip install Appium-Python-Client
-
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
The Appium Python Client is fully compliant with the Selenium 3.0 specification draft, with some helpers to make mobile testing in Python easier. The majority of the usage remains as it has been for Selenium 2 (WebDriver), and as the official Selenium Python bindings begins to implement the new specification that implementation will be used underneath, so test code can be written that is utilizable with both bindings.
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 webdriverFrom 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:
# Android environment
import unittest
from appium import webdriver
desired_caps = {}
desired_caps['platformName'] = 'Android'
desired_caps['platformVersion'] = '4.2'
desired_caps['deviceName'] = 'Android Emulator'
desired_caps['app'] = PATH('../../../apps/selendroid-test-app.apk')
self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)# iOS environment
import unittest
from appium import webdriver
desired_caps = {}
desired_caps['platformName'] = 'iOS'
desired_caps['platformVersion'] = '7.1'
desired_caps['deviceName'] = 'iPhone Simulator'
desired_caps['app'] = PATH('../../apps/UICatalog.app.zip')
self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)The methods that do change are...
For mobile testing the Selenium methods for switching between windows was previously commandeered for switching between native applications and webview contexts. Methods explicitly for this have been added to the Selenium 3 specification, so moving forward these 'context' methods are to be used.
To get the current context, rather than calling driver.current_window_handle you
use
current = driver.current_contextThe available contexts are not retrieved using driver.window_handles but with
driver.contextsFinally, to switch to a new context, rather than driver.switch_to.window(name),
use the comparable context method
context_name = "WEBVIEW_1"
driver.switch_to.context(context_name)This allows elements in iOS applications to be found using recursive element search using the UIAutomation library. This method is supported on iOS devices that still support UIAutomation, that is, versions which predate XCUITEST.
Adds the methods driver.find_element_by_ios_uiautomation
and driver.find_elements_by_ios_uiautomation.
el = self.driver.find_element_by_ios_uiautomation('.elements()[0]')
self.assertEqual('UICatalog', el.get_attribute('name'))els = self.driver.find_elements_by_ios_uiautomation('.elements()')
self.assertIsInstance(els, list)This allows elements in an Android application to be found using recursive element
search using the UIAutomator library. Adds the methods driver.find_element_by_android_uiautomator
and driver.find_elements_by_android_uiautomator.
el = self.driver.find_element_by_android_uiautomator('new UiSelector().description("Animation")')
self.assertIsNotNone(el)els = self.driver.find_elements_by_android_uiautomator('new UiSelector().clickable(true)')
self.assertIsInstance(els, list)This method allows finding elements using iOS predicates. The methods take a string in the format of a predicate, including element type and the value of fields.
Adds the methods
driver.find_element_by_ios_predicate and find_elements_by_ios_predicate.
el = self.driver.find_element_by_ios_predicate('wdName == "Buttons"')
self.assertIsNotNone(el)els = self.driver.find_elements_by_ios_predicate('wdValue == "SearchBar" AND isWDDivisible == 1')
self.assertIsInstance(els, list)This method is only for XCUITest driver
This method allows finding elements using iOS class chain. The methods take a string in the format of a class chain, including element type.
Adds the methods
driver.find_element_by_ios_class_chain and find_elements_by_ios_class_chain.
el = self.driver.find_element_by_ios_class_chain('XCUIElementTypeWindow/XCUIElementTypeButton[3]')
self.assertIsNotNone(el)els = self.driver.find_elements_by_ios_class_chain('XCUIElementTypeWindow/XCUIElementTypeButton')
self.assertIsInstance(els, list)Allows for elements to be found using the "Accessibility ID". The methods take a
string representing the accessibility id or label attached to a given element, e.g., for iOS the accessibility identifier and for Android the content-description. Adds the methods
driver.find_element_by_accessibility_id and find_elements_by_accessibility_id.
el = self.driver.find_element_by_accessibility_id('Animation')
self.assertIsNotNone(el)els = self.driver.find_elements_by_accessibility_id('Animation')
self.assertIsInstance(els, list)In order to accommodate mobile touch actions, and touch actions involving multiple pointers, the Selenium 3.0 draft specifies "touch gestures" and "multi actions", which build upon the touch actions.
move_to: note that use keyword arguments if no element
The API is built around TouchAction objects, which are chains of one or more actions to be performed in a sequence. The actions are:
The perform method sends the chain to the server in order to be enacted. It also empties the action chain, so the object can be reused. It will be at the end of all single action chains, but is unused when writing multi-action chains.
The tap method stands alone, being unable to be chained with other methods. If you need a tap-like action that starts a longer chain, use press.
It can take either an element with an optional x-y offset, or absolute x-y coordinates for the tap, and an optional count.
el = self.driver.find_element_by_accessibility_id('Animation')
action = TouchAction(self.driver)
action.tap(el).perform()
el = self.driver.find_element_by_accessibility_id('Bouncing Balls')
self.assertIsNotNone(el)In addition to chains of actions performed within a single gesture, it is also possible to perform multiple chains at the same time, to simulate multi-finger actions. This is done through building a MultiAction object that comprises a number of individual TouchAction objects, one for each "finger".
Given two lists next to each other, we can scroll them independently but simultaneously:
els = self.driver.find_elements_by_class_name('listView')
a1 = TouchAction()
a1.press(els[0]) \
.move_to(x=10, y=0).move_to(x=10, y=-75).move_to(x=10, y=-600).release()
a2 = TouchAction()
a2.press(els[1]) \
.move_to(x=10, y=10).move_to(x=10, y=-300).move_to(x=10, y=-600).release()
ma = MultiAction(self.driver, els[0])
ma.add(a1, a2)
ma.perform();There are a small number of operations that mobile testers need to do quite a bit that can be relatively complicated to build using the Touch and Multi-touch Action API. For these we provide some convenience methods in the Appium client.
This method, on the WebDriver object, allows for tapping with multiple fingers, simply by passing in an array of x-y coordinates to tap.
el = self.driver.find_element_by_name('Touch Paint')
action.tap(el).perform()
# set up array of two coordinates
positions = []
positions.append((100, 200))
positions.append((100, 400))
self.driver.tap(positions)Swipe from one point to another point.
Zoom in on an element, doing a pinch out operation.
Zoom out on an element, doing a pinch in operation.
There are times when you want, in your tests, to manage the running application, such as installing or removing an application, etc.
The method driver.background_app sends the running application to the background
for the specified amount of time, in seconds. After that time, the application is
brought back to the foreground.
driver.background_app(1)
sleep(2)
el = driver.find_element_by_name('Animation')
assertIsNotNone(el)To check if an application is currently installed on the device, use the device.is_app_installed
method. This method takes the bundle id of the application and return True or
False.
assertFalse(self.driver.is_app_installed('sdfsdf'))
assertTrue(self.driver.is_app_installed('com.example.android.apis'))