二、如何使用Airtest API 文档

1. 前言

在之前的AirtestIDE使用文档中,我们更多的是介绍如何使用IDE提供的自动录制或者辅助录制功能来编写我们的Airtest脚本,但实际上,为了编写出更多更复杂的Airtest脚本,我们更建议大家学会使用 Airtest API 文档查阅更多的API来帮助我们实现更多复杂的自动化操作

打开Airtest API的官方文档,我们可以从左侧的目录中看到,这里包含了1份Airtest的快速上手文档,还有跨平台和平台相关的API等:

image-20211028155747096

下文我们将详细介绍,我们该如何使用这个API文档。

2. Airtest快速上手文档

阅读API文档中这部分的内容,可以快速让我们了解Airtest的支持情况以及简单示例(内容相对简单,更多关于Airtest脚本的详细内容还是建议阅读本文档的Airtest脚本入门章节内容):

image-20211028160114618

3. 跨平台的Airtest核心API

这个模块包含了Airtest跨平台的各种API,也是Airtest的核心API:

image-20211028160413961

1)查看“支持平台”

在这个模块下面,我们可以查看API的平台支持情况,比如 :

  • touch接口支持Android、iOS和Windows平台
  • start_app接口支持Android和iOS平台
  • clear_app接口仅仅支持Android平台

image-20211028160753761

支持平台的意思就是,该API可以在支持的平台下运行,比如 touch 接口的支持平台是3个,那就意味着这个接口可以在Android设备、iOS设备甚至Windows窗口上面运行。

所以关注API的支持平台是非常重要的,因为Airtest提供了跨平台的API,也提供了平台专用的API,如果同学们强行把接口用在了不支持的平台上,那势必会产生各种报错,比如 clear_app 仅支持Android平台,那如果同学们不小心把它用在了iOS平台上,就会出现错误。

2)查看“参数”

除了需要关注核心API的支持平台情况,我们还需要关注API的参数情况。

举个最简单的例子,我们之前在录制脚本的时候,都知道 touch 接口里面的是一张图片,那是不是这个接口只能传入一张图片呢?这就需要我们到API文档查看一下它的参数情况了:

image-20211028161710393

可以看到这个API的参数情况,我们不仅可以给 touch 传入一个图片实例,还可以传入1个绝对坐标,类似 touch([100,100]) ;甚至我们还可以设置点击次数,比如我们想点击2次,即双击,可以设置 times=2 ,还有一些平台相关的参数。

知道API的参数情况,可以帮助我们实现更多操作效果。

3)查看“返回值”

有时候我们还需要关注API的返回值,比如我们想要拿到某个图片在当前画面的匹配坐标,该如何做呢?查一下各个API的返回值,可以看到有好几个API都可以满足我们的要求:

image-20211028165926665

再比如,我们想要实现1个功能,如果存在某个图片,就进行点击,否则就进行别的操作,我们也可以从API的返回值来找到适合的接口:

  1. if exists(图片):
  2. touch(图片)
  3. else:
  4. pass

image-20211028170150611

可以看到,exists 接口,若找到了目标,返回目标的坐标,if 成立,可以对目标进行点击操作;若没有找到目标,则返回 falseif 不成立,执行别的操作。

4)查看“示例”

另外,我们在Airtest 的核心API模块里,给各个API提供了示例脚本,方便同学们参考学习:

image-20211028170747955

4. 平台相关的API

这个模块下面包含了一些平台专用的API,包含Android、iOS和Windows平台:

image-20211028173915741

1)平台专属的API

每个平台都有一些专属的API,比如录屏模块,就是Android平台特有的:

image-20211028174159607

有时候,平台通用的API并不能满足我们的脚本编写需求,我们可以到平台专用的API这里查找下,是否有符合我们需求的专用API可以使用。

2)平台专属的API 参数

有一些接口,在通用平台下,只包含几个通用的参数,但在专用平台下,还会额外支持一些参数;比如 touch 接口,在通用平台下,支持传入点击位置pos和点击次数times这2个参数;但是在安卓专用模块下,还支持1个额外的参数,点击时长-duration

image-20211028173309397

image-20211028173344147

5. 在API文档进行搜索

在编写Airtest脚本时,我们要善于利用API文档的搜索功能,举个例子,同学们经常问到一些问题,我们完全可以借助搜索API文档来实现:

比如,有同学会问,点击图片我会了,但如何实现双击呢?此时我们可以到Airtest的API文档里面搜touch,先从核心模块找起:

image-20211028174639561

发现跨平台的touch接口,支持设置点击次数:

image-20211028174735054

那我们只要给这个touch传入times=2,即可实现双击。

那又会有同学问,我想实现长按呢?比如点击2秒或者更长时间,那我们刚才看过了核心API的touch,没有参数可以实现这个效果,那我们再到平台专用模块里面去查一下,假设此时是Android设备:

image-20211028175048745

image-20211028175126263

可以看到,Android平台专用模块下的touch,是支持传入点击时长-duration的,那此时只需要给touch传入duration=2或者更长时间,即可达到我们想要的效果。