Macaca Macaca 测试 Android 原理解析 － UIAutomator 篇
前言
用 Macaca 可以快速、便捷地进行安卓 native 的自动化测试，用简洁的 js 语法，写下用例，然后执行 Macaca CLI 命令，就可以看到安卓的手机在按照你的指令自动进行用例操作。相关文章可参考：
使用 Macaca 测试 Android 应用
Macaca 对于 native 的自动化测试主要利用了 UIAutomator 。Macaca 是如何将这一 Java 写成的工具集成到自身的呢，本文将对此进行分析，让大家更加快乐、明白地使用 Macaca 。
自动化利器－UIAutomator
首先介绍下 UIAutomator。UIAutomator 是随 Android SDK 一起发布的一个测试框架，该测试框架提供了一系列 API，利用这些 API 我们可以编程和安卓 App 进行交互，例如：打开设置菜单，点击，滑动等。并且可以对设备进行物理指令操作，如：旋转设备，获取设备分辨率等。该测试框架的 jar 包可以在 SDK 的安装目录中找到:
$ANDROID_HOME/platforms/android-$version/uiautomator.jar
其中 $version 为安装的 SDK 版本号
下面是 UIAutomator 框架的类图：
图中，用来写测试用例的常用几个类简介：
-
UiObject代表一个设备上可见的 ui 元素 -
UiScrollable用来在可滚动 ui 容器中查找元素。因为有的元素要滚动后才可以看到 -
UiSelector条件对象，和 UiObject 对象一起使用来根据条件查找元素 -
UiCollectionui 元素对象的集合 -
UiDevices通过 getUiDevices 方法获得一个单例的对象，通过该对象可以进行一些设备相关的操作
测试原理
Macaca 主要有两个模块来负责操作设备的自动化测试，一个是 macaca-adb，一个是 uiautomator-client。macaca-adb 用 Nodejs 对安卓 adb 命令进行了包装，以供其他 node 模块调用，可以用其来进行模拟器的启动，端口号映射，获取设备等操作。uiautomator-client 模块是我们分析的主角。
Java 端测试用例编写方法
我们先来看 Java 端一般是如何跑 UIAutomator 测试用例的。创建一个 Java 工程，编写用例类，UIAutomator 的测试入口是一个 UIAutomatorTestCase 的子类，范例如下：
import com.android.uiautomator.testrunner.UiAutomatorTestCase;
public class test extends UiAutomatorTestCase {
public void testMain() throws UiObjectNotFoundException {
// 用例代码
}
}
然后在该工程根目录下执行命令
android create uitest-project
会在工程下生成一个 ant 的 build.xml 文件，接着用 ant 对该工程进行编译打包，在工程的 bin 目录下生成 jar 包。
将生成的 jar 包用adb push到安卓设备上，然后执行
adb shell uiautomator runtest jar包名 -c 测试类名
最后我们的 UIAutomator Java 用例代码便运行起来了。
Macaca 的做法
uiautomator-client 模块会在本地机器和安卓设备之间建立 socket 连接，然后自动化指令就通过 socket 进行传输。既然是建立 socket ，那么必然有客户端和服务端的 socket 服务建立过程。本机上的 socket 服务建立用 Nodejs 建立并监听即可。对于手机端的 socket 服务建立，我们把 Java 建立 socket 的过程放在 UIAutomator 用例的入口处，如下：
import com.android.uiautomator.testrunner.UiAutomatorTestCase;
public class test extends UiAutomatorTestCase {
public void testMain() throws UiObjectNotFoundException {
// 建立socket服务
initSocketServer();
}
}
然后我们将 “ Java 端测试用例编写方法” 这一小节描述的过程用 Nodejs 的代码进行封装，所涉及的 adb 命令由 macaca-adb 模块搞定，包括 ant 编译命令也通过 Nodejs 来封装执行，生成一个驱动 jar 包，最后将这个 UIAutomator 驱动模块 push 到安卓设备并启动，这样安卓设备就建立 socket 服务完毕。下面从代码上详细分析一下该过程。
安装了 uiautomator-client，并成功跑过一次安卓测试用例的同学，可以在 uiautomator-client 的安装目录下查找 uiautomator-client 文件夹，可以发现该文件夹下包含了一个标准的 UIAutomator 的测试用例工程：
这个工程就是被上图中 scripts 文件夹下的 build.js 创建的。Macaca UIAutomator 驱动的编译过程就是在 build.js 中进行的。
我们来看 build.js 中的逻辑，先通过 checkEv 函数来检测系统环境变量 ANDROID_HOME 有没有配置，因为需要用到 SDK 目录下的 Android Tools 工具：
var checkEnv = function() {
return JAVA_HOME.getPath().then(javaHome => {
console.log('JAVA_HOME is set to ' + javaHome);
var env = global.process.env;
if (!env.ANDROID_HOME) {
console.log('ANDROID_HOME is not set');
throw new Error('ANDROID_HOME is not set');
}
var android = isWindows ? 'android.bat' : 'android';
var androidTool = path.resolve(env.ANDROID_HOME, 'tools', android);
if (!_.isExistedFile(androidTool)) {
console.log('`android` command was not found');
throw new Error('`android` command was not found');
}
var sdkVersion = selectAndroidSdkSync();
if (!sdkVersion) {
console.log('no avaliable sdk');
throw new Error('no avaliable sdk');
}
sdkVersion = sdkVersion[sdkVersion.length - 1];
var args = ['create', 'uitest-project', '-n', fileName, '-t', sdkVersion, '-p', '.'];
return [androidTool, args];
});
};
然后用 createUITest 函数来创建一个标准的 UIAutomator 测试工程，并生成了 ant build 文件：
var createUITest = function(res) {
var androidTool = res[0];
var args = res[1];
return new Promise((resolve, reject) => {
var createProcess = spawn(androidTool, args, {
cwd: cwd
});
createProcess.on('error', err => {
console.log(err);
reject(err);
});
createProcess.stdout.setEncoding('utf8');
createProcess.stderr.setEncoding('utf8');
createProcess.stdout.on('data', data => {
console.log(data);
});
createProcess.stderr.on('data', data => {
console.log(data);
});
createProcess.on('exit', code => {
if (code !== 0) {
reject(new Error('setup failed'));
} else {
resolve();
}
});
});
};
然后通过 buildBootstrap 函数来进行 Java 编译，其中用到一个 ant 的 npm 包:
var buildBootstrap = function() {
return new Promise((resolve, reject) => {
var buildProcess = spawn(ant, ['build'], {
cwd: cwd
});
buildProcess.on('error', err => {
return reject(err);
});
buildProcess.stdout.setEncoding('utf8');
buildProcess.stderr.setEncoding('utf8');
buildProcess.stdout.on('data', data => {
console.log(data);
});
buildProcess.stderr.on('data', data => {
console.log(data);
});
buildProcess.on('exit', code => {
if (code !== 0) {
reject(new Error('build failed'));
} else {
console.log(fileName + ' build success!');
resolve();
}
});
});
};
需要特别注意的是，设备端 socket 服务监听的是设备端口，本地电脑端服务监听的本机的端口，要想连通这两端的 socket，需要用 adb 工具进行端口映射，命令如下：
adb forward tcp:A tcp:B
通过该 adb 命令可以将发往本机 A 端口的数据重定向到安卓设备的 B 端口。
有了 socket 连接，就可以将测试指令发往 UIAutomator 驱动，驱动根据不同的指令参数去执行用 UIAutomator API 写成的 Java 用例。
小结
将上一小节的分析用一个图来进行总结，给大家一个全局认识
用 UIAutomator API 编写自动化代码
可以看到，最终我们的自动化指令是要通过 UIAutomator 这个框架来驱动的，如何用该框架的 API 进行自动化代码编写读者可以参照网上的各种教程，这里笔者通过 Swipe 操作的实现来简单地介绍 Macaca 是如何使用该框架 API 的。
首先将操作指令都用一个类表示：Swipe.java，它实现 execute 方法，通过 socket 收到 json 字符串指令后，解析字符串，根据字符串去调用对应的指令类实例的 execute 方法。范例如下：
import com.android.uiautomator.core.UiDevice;
public class Scroll {
public String execute(JSONObject args) throws JSONException {
try {
boolean result = UiDevice.getInstance().swipe(50, 300, 50, 10, 1000);
return success(result);
} catch (final Exception e) {
return failed("UnknownError");
}
}
}
其中 UiDevice 是 UIAutomator 框架下的类，且是单例的，通过getInstance获取实例后调用swipe来模拟设备上的手势滑动。
在 Macaca 测试用例中用driver.swipe(startX, startY, endX, endY, duration)的方式编写滑动用例，下面给出两种滑动的自动化效果范例：
- 上下滑动：
- 左右滑动
总结
本文简要分析了 Macaca 利用 UIAutomator 的原理，抛砖引玉。但是实际的代码实现需要考虑更多的东西，也更为复杂，且这部分也仅仅是 Macaca 的一个模块。但是 Macaca 代码都是开源的，觉得本文写的不够详细或有兴趣深入的同学可以亲自去看看其源码。Macaca 也还有很多不足，欢迎大家参与其中，多提意见多支持。_^
本文所涉及相关模块的 github 地址：
两个范例的代码地址（打包好的 apk 均命名为 app-release.apk 放在工程根目录下，可直接在用例中引用）：
赞啊！
很走心的文章，期待其他关于 Android 的部分
赞👍
driver.swipe(startX, startY, endX, endY, duration) 在 IOS 上实现没有效果，能提供下在 IOS 上的例子么
#4 楼 @lylh iOS 的确没有这个 https://github.com/alibaba/macaca/issues/69
