3.1. 脚本编写

我该如何开始写脚本?

我们提供的两个用于支持脚本编写、运行的仓库 AirtestPoco 库,是Python第三方库,因此脚本的编写需要有 一定的Python基础 。若对 Python 语法不熟悉,网络上有不少非常优秀的Python教程可以学习,例如 廖雪峰的Python新手教程

在脚本编写过程中,可以根据需求在里面混合使用 AirtestPoco ,也可以自由加入自己想用的其他python第三方库完成更加强大的功能。

但是请注意,可以 混用 AirtestPoco 代码,不代表是在同一条语句中混合使用Airtest的图片与Poco的语句,请各位在编写时注意每个库自己的API和语法。

在开始你的脚本编写工作前,可以先读一读官网提供的 教程 ,可以帮助你更快地上手。

开发环境的准备

如果使用AirtestIDE来编写脚本,只需要在 官网 下载最新版本AirtestIDE,解压即可直接使用。AirtestIDE内置了Python3.6.5,airtest和poco环境,本地无需安装python环境就能 直接使用

若需要使用python命令行运行脚本,请参考 运行脚本 中的 环境部署 章节。

如果想要使用其他需要安装的Python第三方库,或者Python2环境,请先进行本地python的 环境部署 ,然后在AirtestIDE设置中添加本地的Python.exe路径,详情请参考 IDE配置

Airtest与Poco相关问题

Airtest和Poco的区别

Airtest框架基于图像识别,写脚本的时候类似这样:

http://airtest.netease.com/tutorial/gif/airtest_auto_record.gif

Poco框架基于UI控件搜索,写脚本的时候是这样的:

http://airtest.netease.com/tutorial/gif/poco_auto_record.gif

Airtest和Poco如何初始化

在AirtestIDE中新建的脚本,后缀都为 .air ,但实际上我们在运行的时候, 运行的是.air目录下的同名.py文件 。因此,就像一个普通的python脚本那样,当我们需要使用airtest的接口时(例如touch指令),我们需要在.py脚本的最前面import airtest的api。我们可以在AirtestIDE里新建一个脚本,就能看到默认的初始化代码:

# -*- encoding=utf8 -*-
__author__ = "user"

from airtest.core.api import *
# 从api中import接口后,就能直接使用airtest的各个接口了
auto_setup(__file__)  # 自动初始化设备

关于airtest提供的更多API信息,请参考 Airtest文档

关于如何连接上我想要的对应设备,请参考 如何连接手机/windows窗口

与Airtest不同的是,Poco需要在使用前,插入一段初始化代码,如图:

http://airtest.netease.com/docs/cn/_images/4-poco_manual_record.gif

关于Poco的初始化,请参考 How to use Poco

如何用命令行运行脚本

关于命令行运行脚本,我们在 运行脚本 中做了非常详尽的介绍,请查阅。

批量运行脚本的方式我们暂时未提供,若有需求,可以自行写调度脚本来运行。

在AirtestIDE里写的脚本丢失了

第一次打开AirtestIDE时,会默认帮忙在系统temp目录下新建一个空脚本,方便大家熟悉软件功能和上手编写脚本。请在脚本编写的工作中,尽量避免将脚本保存在系统目录、或无权限读写的目录。如果是MacOS,请 不要将脚本保存在AirtestIDE.app的目录里 (例如: /Applications/AirtestIDE.app/Contents/MacOS ),因为一旦重装应用,将会覆盖掉该目录,导致脚本丢失。

请务必选择一个合适的、有存取权限的目录来存放你的脚本。

常见脚本逻辑与代码示例

请参考 9.3 常见脚本逻辑与代码示例

在AirtestIDE中录制Airtest语句

AirtestIDE为录制带截图的Airtest语句,提供了很多便利,录制方法请参考 2. Airtest脚本辅助录制

Airtest API文档

Airtest的常用API大部分都列在了AirtestIDE里的Airtest辅助窗中,在使用各种常见的截图语句时,鼠标移动到按钮上即可看到每个接口的常用参数与返回值信息,非常方便。

../_images/airtest_ide_api.png

想要查阅更详细的API信息,请翻阅 airtest.core.api 页面。

airtest.core.api 中的API信息,是各平台通用的API和通用参数。而同一个接口在不同的平台下,可能会有不同的参数,甚至有些额外的特有接口。例如,在 Android 设备上, touch 接口是点一下某个位置,但是在 Windows 中,我们可能会有双击、右键操作,这时候就需要去查阅对应平台的对应接口文档了,如图:

../_images/airtest_api_win.png

在我们的快速上手教程 如何为你的游戏写一个测试脚本 中的进阶阅读章节,我们以 touch 为例,详细介绍了它的使用方式和文档查阅方式,大家可以作为参考。

如果你的脚本涉及到 Android 设备,以及想要使用一些 Android 设备上的独有接口(例如想便捷地调用 adb shell ls 这样的指令),可以参考教程- 在Android手机上进行测试 ,里面详细地介绍了几种Android设备专用的接口和调用方式。其他的平台也与此类似,请通过查阅相关的教程来获取更多信息。

更多细节,请参考 第5章 Airtest

在AirtestIDE中使用Poco

同样地,AirtestIDE为Poco的录制和使用提供了很多便捷的功能,详情请参考 3. Poco 辅助功能

Poco API文档

在我们提供的快速上手 如何为你的游戏写一个测试脚本 教程中,我们使用一个游戏作为例子详细阐述了如何上手编写airtest和poco脚本,非常建议新手事先进行阅读。

更多细节,请参考 第6章 Poco

新建.air脚本与纯.py脚本[新]

在Airtest中,原先的默认脚本后缀名为 .air ,实际上它是一个文件夹,里面存放了与 .air 同名的 .py 文件,以及相关的图片文件。在运行脚本时,实际上依然使用了python调用了里面的 .py 文件,因为Airtest本质上是一个Python的第三方库。(关于如何运行脚本,请点 这里 。)

因此实际上,在普通的 .py 文件中,一样可以调用Airtest的接口,由于这样的需求与日俱增,我们在AirtestIDE和Airtest中,都增加了一个便捷创建py脚本的功能。参考的示例代码可以点 这里 查看,其中关键的初始化代码如下:

from airtest.core.api import *
from airtest.cli.parser import cli_setup

if not cli_setup():
    auto_setup(__file__, logdir=True, devices=[
        "Android:///?cap_method=javacap&ori_method=adbori",
    ])

上面这段代码的意思是说,当使用 python xxx.py 来运行本文件,不带任何命令行参数时,则自动使用 auto_setup 这个接口来对airtest相关的参数进行初始化。这样只需要在写py脚本时,填写好期望的参数就能直接用 python xx.py 指令来运行脚本。而原先的 ``airtest run xx.air –devices xx `` 也不受影响,只要脚本检测到传入了命令行参数,就依然优先使用命令行参数来初始化airtest。

同时,在AirtestIDE中,若想直接新建一个py文件,请在新建脚本时,选择 .py Pure Python (For Advanced Users) ,随后会弹出python文件的设置窗口:

../_images/pycli.png

里面的配置项有:

  • Save Path: 文件保存路径,必填项,选择好路径后才能继续配置其他选项
  • Log Directory: 脚本运行时的log保存路径,默认为.py文件所在目录下的 log/ 目录
  • Devices: 可以选择自动使用当前已连接的手机设备对devices参数进行初始化,也可以以后再填写
  • Project Root: 项目的父目录,方便未来使用 using 语句引入同一父目录的其他子文件夹

在配置完所需要的选项后,点击ok按钮,将会自动以刚才的配置内容新建一份模板python文件,接下来只需要像编写一个普通py文件那样来编写脚本就可以了。

纯.py脚本的报告生成

关于如何生成.air脚本的报告,在文档 4.2.3 生成运行结果报告 中有很详细的描述。如果在纯.py脚本中,需要通过代码来生成报告,同样可以参考文档中描述的内容。

在AirtestIDE中,假如打开了.py文件,并且在运行完脚本后,希望能直接使用IDE的一键生成报告功能的话,需要在点击生成报告按钮时,手工指定运行脚本时的log目录所在路径:

../_images/pycli-report.png

如何调试脚本

目前AirtestIDE暂不支持断点调试功能,因此调试脚本只能通过print log等较为简单的方式。

但是由于Airtest的截图语句涉及到图像识别的准确率问题,需要反复运行和调试才能确定合适的图片与识别阈值,因此我们提供了一种 选中部分代码单独运行 的调试功能:

../_images/debug_code.png

可以选中部分代码后点击鼠标右键,选择 只运行选中代码,即可单独运行被选中的代码段落。需要注意的是,该单独运行代码的功能不会执行到脚本中其他代码里的内容,可能会出现别处的变量未能初始化等情况,因此只能作为辅助工具使用,不能完全依赖它来调试整个脚本。

脚本的自动保存与缓存文件找回

在脚本编写工作中,我们十分推荐各位尽可能地利用一些版本管理软件,对编写的脚本进行管理,这样能避免很多脚本的丢失与多人协作的问题。

在使用AirtestIDE编写脚本时,我们将会每隔30秒对当前编辑窗口的脚本进行一次自动保存工作,避免遗忘保存导致的脚本遗失问题。

然而在一些极端情况下(电脑蓝屏、死机等),还有可能出现脚本编辑框显示错乱,导致原先的脚本丢失的问题。因此我们新增了一个脚本缓存找回功能,每当 手动选择保存 或是 运行脚本 时,都认为当前文件是一个完好的脚本文件,因此会自动在系统缓存目录下另存一份脚本的纯文本内容。如果遇到了异常情况,需要找回以前保存过的脚本的话,可以在脚本标题上点击鼠标右键:

../_images/recovery_file.png

随后的弹窗中,有3个可选项:

../_images/recovery_file2.png

最左边的按钮是一键自动恢复,能将最近一次的缓存文件内容恢复到当前编辑窗口中。中间的按钮是打开缓存文件夹,打开后将会看到一些纯文本文件,命名规则是将脚本文件的路径中的 :\/ 等符号替换成 % ,最后以时间戳进行结尾,可以自行找到编辑中的文件名对应的缓存文件后,用文本编辑器打开,就可以看到自动保存的内容了。