除了标准的W3C API接口，Uiautomator2还提供了一系列扩展接口来支持Android平台相关的操作。本文所有测试代码的前提是已经安装Appium和相关环境（例如JDK、Android SDK、AVD模拟器），可以参考Appium环境搭建。
应用程序（APP）管理
1.1 检查被测应用是否已经安装
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
appId |
string |
yes |
appId是待检测的应用ID，和package名称一致，可以通过ADB或者current_package属性获取。 |
com.example.android.contactmanager |
接口返回值：True或False
举例：
# -*- coding: utf-8 -*-
import pytest
from appium import webdriver
from appium.options.android import UiAutomator2Options
from appium.webdriver.appium_service import AppiumService
# 开启服务端
APPIUM_HOST = '127.0.0.1'
APPIUM_PORT = 4723
@pytest.fixture(scope="session")
def start_appium_service():
server = AppiumService()
server.start(args=['--address', APPIUM_HOST, '-p', str(APPIUM_PORT)], timeout_ms=60000)
yield server
server.stop()
# 创建客户端到服务端的会话
def create_appium_session_by_api(custom_opts = None, appium_host = APPIUM_HOST, appium_port = APPIUM_PORT):
options = UiAutomator2Options()
if custom_opts is not None:
options.load_capabilities(custom_opts)
return webdriver.Remote(f'http://{appium_host}:{appium_port}', options=options)
# !检测appu是否已经安装
def test_check_if_app_installed(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
assert driver.is_app_installed(driver.current_package) == True
driver.quit()
1.2 安装/升级APP
接口参数说明：
| 称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
appPath |
string |
yes |
被测设备本地文件系统上.apk(s)的路径，或远程url链接。注意：需要提供全路径（不能是相对路径）！！！ |
/tmp/ContactManager.apk |
timeout |
number |
no |
等待app安装完成的超时时间，单位是毫秒，默认值是6000ms。 |
60000 |
allowTestPackages |
boolean |
no |
如果需要安装测试包，将该参数设置为true，默认值是false。 |
true |
useSdcard |
boolean |
no |
如果需要将app安装到SD卡，将该参数设置为true，默认值是false
|
true |
grantPermissions |
boolean |
no |
设置为true可以确保app在完成安装后请求的权限自动满足，需要Android 6+。targetSdkVersion必须大于等于23，Android版本需要6（API level 23）及以上。默认值是false。 |
true |
replace |
boolean |
no |
如果被测设备上应用已经安装，而你又不想升级或者重新安装该应用，将replace设置为false，并且此时调用接口会抛出错误。参数默认值是true。 |
false |
备注：本小结示例中的APP来源于https://github.com/appium/sample-apps/raw/master/pre-built/ContactManager.apk。并假设下载之后该apk存放的全路径是/tmp/
举例1：使用本地路径安装，安装后启动APP可能会需要权限，因此在安装的时候将grantPermissions 设置为true保证自动授予APP启动时需要的权限。
# !使用本地路径安装APP
def test_install_app_by_localfile(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
assert driver.is_app_installed(ContactManagerAppId) == True
driver.start_activity(ContactManagerAppId, ".ContactManager")
assert driver.current_package == ContactManagerAppId
driver.quit()
举例2：使用远程url路径进行安装。
# !使用远程url路径安装APP
def test_install_app_by_remote_url(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
driver.install_app("https://github.com/appium/sample-apps/raw/master/pre-built/ContactManager.apk", grantPermissions=True)
assert driver.is_app_installed(ContactManagerAppId) == True
driver.start_activity("com.example.android.contactmanager", ".ContactManager")
assert driver.current_package == ContactManagerAppId
driver.quit()
举例3：使用capabilities初始化APP路径。同样地，自动授予APP启动时请求的权限，对应的参数是appium:autoGrantPermissions。
# !使用Capability参数初始化安装APP
def test_install_app_by_capability(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
"appium:app": "/tmp/ContactManager.apk",
"appium:autoGrantPermissions": True,
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
assert driver.is_app_installed(ContactManagerAppId) == True
driver.start_activity("com.example.android.contactmanager", ".ContactManager")
assert driver.current_package == ContactManagerAppId
driver.quit()
1.3 激活/启动APP
在必要的时候激活或启动应用，该动作模拟点击应用程序图标操作，APP启动需要时间，因此后续动作需要等待APP正常启动，本小结的例子就是延时1S。
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
appId |
string |
yes |
appId是待启动的应用ID，和package名称一致，可以通过ADB或者current_package属性获取。 |
com.example.android.contactmanager |
举例：假设已经安装好APP。另外一种方式是通过start_activity指定appId和activity来启动应用。
import time
# !启动APP
def test_activate_app(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
# 先安装
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
ContactManagerAppId = "com.example.android.contactmanager"
driver.activate_app(ContactManagerAppId)
time.sleep(1) # 延时1S等待应用启动
assert driver.current_package == ContactManagerAppId
driver.quit()
1.4 卸载APP
卸载已经安装的应用，如果待卸载的应用并未安装，则卸载动作会被忽略。
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
appId |
string |
yes |
appId是待卸载的应用ID，和package名称一致，可以通过ADB或者current_package属性获取。 |
com.example.android.contactmanager |
keepData |
boolean |
no |
应用被卸载后，是否还保留数据和缓存，默认是False。 |
True |
timeout |
int |
no |
等待应用卸载的超时时间，单位是毫秒，默认值是20000 ms。 |
10000 |
# !卸载APP
def test_remove_app(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
# 先安装
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
assert driver.is_app_installed(ContactManagerAppId) == True
driver.remove_app(ContactManagerAppId) # 移除安装的应用
assert driver.is_app_installed(ContactManagerAppId) == False
driver.quit()
1.5 结束APP
结束正在运行的APP，并检测状态确保APP已经被关闭或者检测的超时时间到。当把超时时间设置的很小甚至为0的时候（UIAutomator驱动的2.9.0版本开始支持），可以跳过状态检测。
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
appId |
string |
yes |
appId是待结束的应用ID，和package名称一致，可以通过ADB或者current_package属性获取。 |
com.example.android.contactmanager |
timeout |
int |
no |
等待应用结束的超时时间，单位是毫秒，默认值是500 ms。 |
10000 |
# !结束APP
def test_terminate_app(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
# 先安装
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
assert driver.is_app_installed(ContactManagerAppId) == True
# 启动
driver.activate_app(ContactManagerAppId)
time.sleep(1) # 延时1S等待应用启动
assert driver.current_package == ContactManagerAppId
driver.terminate_app(ContactManagerAppId) # 结束应用
assert driver.current_package != ContactManagerAppId
driver.quit()
1.6 启动APP的activity（Android应用的activity参考关于intent和activity的简介）
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
intent |
string |
yes |
待启动activity的全称。 |
com.example.android.contactmanager/.ContactManager |
user |
number或string
|
no |
用于启动服务的用户ID，默认使用当前的用户ID。 |
1001 |
wait |
boolean |
no |
如果设置为true，则阻塞该调用，直到activity处理完成后返回，默认是false。 |
false |
stop |
boolean |
no |
如果设置为true，则启动activity之前强制停止APP。 |
false |
windowingMode |
integer |
no |
启动activity使用的窗口模式，具体请参考这里
|
1 |
activityType |
integer |
no |
activity类型，具体请参考这里
|
1 |
action |
string |
no |
动作名称，为am（Activity Manager）的-a参数指定的值。 |
android.intent.action.MAIN |
uri |
string |
no |
唯一资源标识符，为am的-d参数指定的值。 |
https://appium.io/ |
mimeType |
string |
no |
Mime类型，为am的-t参数指定的值。 |
application/json |
identifier |
string |
no |
可选标识符，为am的-i参数指定的值。 |
my_identifier |
categories |
string或Array<string>
|
no |
一个或多个项目名称，为am的-c参数指定的值。 |
android.intent.category.LAUNCHER |
component |
string |
no |
组件名称，为am的-n参数指定的值。 |
com.myapp/com.myapp.SplashActivity |
package |
string |
no |
包名称，为am的-p参数指定的值。 |
com.myapp |
extras |
Array<Array<string>> |
no |
可选intent参数，必须表示成二维数组的形式。细节请参考官方文档
|
[['s', 'varName1', 'My String1'], ['s', 'varName2', 'My String2'], ['ia', 'arrName', '1,2,3,4']] |
flags |
string |
no |
intent的特定启动标志，以十六进制字符串表示。具体请参考官方文档
|
0x10200000 是两个标志的组合: 0x10000000 FLAG_ACTIVITY_NEW_TASK
|
举例：
# !启动activity
def test_start_activity(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
# 先安装
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
driver.start_activity("com.example.android.contactmanager", ".ContactManager")
assert driver.current_activity == ".ContactManager"
driver.quit()
1.7 查询APP的状态
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
appId |
string |
yes |
appId是被检查的应用ID，和package名称一致，可以通过ADB或者current_package属性获取。 |
com.example.android.contactmanager |
返回值的状态说明：
0：应用未安装
1：应用已安装单未运行
3：应用在后台运行
4：应用在前台运行
举例：
# !查询APP运行状态
def test_query_app_state(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
# 卸载
driver.remove_app(ContactManagerAppId)
assert driver.query_app_state(ContactManagerAppId) == 0
# 安装
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
assert driver.query_app_state(ContactManagerAppId) == 1
# 启动
driver.start_activity(ContactManagerAppId, ".ContactManager")
assert driver.query_app_state(ContactManagerAppId) == 4
driver.quit()
1.8 后台运行APP
将APP置于后台运行，并等待指定的时间（单位是秒），然后尝试恢复到前台运行，该调用的阻塞的，从UIAutomator驱动2.19.0版本开始支持。
接口参数说明：
| 参数名称 | 参数类型 | 参数是否必须提供 | 描述 | 举例说明 |
|---|---|---|---|---|
seconds |
number |
no |
将APP置于后台运行到恢复前台运行等待的秒数，任何负值表示将APP置于后台运行且不恢复（也是默认行为），当使用负数的值时，调用不会阻塞，会立即返回。 |
com.example.android.contactmanager |
举例：
# !将APP置于后台运行
def test_put_app_to_background(start_appium_service):
custom_opts = {
"appium:avd": "testPhone",
}
driver = create_appium_session_by_api(custom_opts)
ContactManagerAppId = "com.example.android.contactmanager"
# 安装
driver.install_app("/tmp/ContactManager.apk", grantPermissions=True)
assert driver.query_app_state(ContactManagerAppId) == 1
# 启动
driver.start_activity(ContactManagerAppId, ".ContactManager")
assert driver.query_app_state(ContactManagerAppId) == 4
# 置于后台运行3秒
driver.background_app(3)
time.sleep(5)
# background_app接口会阻塞，超时时间到了之后会恢复到前台运行
assert driver.query_app_state(ContactManagerAppId) == 4
# 置于后台运行，负数时间，不会恢复到前台了
driver.background_app(-1)
time.sleep(10)
assert driver.query_app_state(ContactManagerAppId) == 3
driver.quit()
