Getting Airtest official introduction and tutorial --Airtest script

Foreword

By reading this section of the tutorial, you will learn the following:

• A detailed analysis Airtest script example
• How to call Airtest interfaces in Python scripts
• Parameter Description picture statement

Airtest Introduction

Airtest is a Python-based UI test automation frameworks, cross-platform, based on image recognition principles for the game and App.

Access on Github  Airtest source address  , you can get more information, but also to welcome you to help complete the project, submit PR, also in issues page  to submit bug or suggestion  .

How to get started quickly

First, Airtest want to write a script, you need to have basic knowledge of grammar Python. While recording capabilities help provide our AirtestIDE, it can easily be recorded in accordance with the procedure script playback operation, but generally speaking, master Python syntax can help us write more widely used and more difficult script error.

If not familiar with the Python syntax, there are many excellent Python tutorial can learn, for example, the network  Python newbie tutorial Liao Xuefeng's .

About Airtest project installation and basic use of a simple example, see Airtest document page  Quick Start  section.

First, a simple script to parse .air

What is .air script

In the download, unzip Airtest exclusive script IDE - after AirtestIDE, click on the "New Script" button, the default suffix to create a .airscript file, .airwhich is exclusive suffix Airtest script.

Let's just open a new script folder, you can actually see the .airscript file is an ordinary folder, which comes with a same name of the .pyfile, AirtestIDE when executing the script is actually executed is inside the .pyfile. In other words, Airtest although the script comes with a suffix, but in essence still is a Python script, follow the Python syntax, we can freely according to the actual needs of importother Python third party libraries.

It is worth noting that .airfolder must have the same name as the .pyfile, or the command line airtest run test.air when running this command will lead to failure.

How to use AirtestIDE record Airtest script

Before watching this tutorial, if you have read our Quick Start tutorial, then you should know that we need to connect a script before recording device . This device may be an Android phone, a Windows window, or iOS devices, etc., please refer to our devices are connected documents, in AirtestIDEconnection in a device as needed.

After successfully connected device, you can Airtest script recording two functions described in the documentation: manual and automatic recording Record button to record a script what you need.

At the same time by using Python's judgment, circulation grammar, let the script to achieve more complex functions, complete the requirements of automated testing.

Airtest script example

This is a simple script example content: (AirtestIDE will automatically Template(xxxx)render these are images)

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

# 初始化环境
from airtest.core.api import *
auto_setup(__file__)

start_app("org.cocos2d.blackjack")

# 模拟点击
touch(Template(r"tpl1556019871196.png", record_pos=(0.204, -0.153), resolution=(1280, 720)))
sleep(2)
swipe(Template(r"tpl1561952588795.png", record_pos=(-0.067, 0.134), resolution=(1280, 720)), vector=[0.2783, 0.0374])
wait(Template(r"tpl1561952704834.png", record_pos=(-0.186, -0.093), resolution=(1280, 720)))

keyevent("BACK")

# 一些简单的逻辑判断
if exists(Template(r"tpl1559100640980.png", record_pos=(-0.33, -0.105), resolution=(1920, 1080))):
    text("test")

# 断言
assert_exists(Template(r"tpl1561952631660.png", record_pos=(-0.373, -0.108), resolution=(1280, 720)), "验证内容存在")

stop_app("org.cocos2d.blackjack")

Initialize the environment

First of all, just like an ordinary Python scripts, we need the very beginning of the code section of the file, write from airtest.core.api import *the main API Airtest all import came in to use the API in the following script.

auto_setup Is an initialization environment interface, the interface used in the document here , it accepts four parameters, we can set the path to the current script, the equipment designated to run the script, set the default log path and setup scripts parent path.

• If you auto_setupdo not pass any parameters, then, Airtest will read the run-time parameters passed on the command line to initialize the environment.
• When AirtestIDE create a script, the default generated code is the most simple initialization code auto_setup(__file__), which means the script as a script file path passed, other parameters default to read the contents of the Run command line parameters passed.

Run the command line script in two forms, command line parameters included device, logsuch as:

• Airtest sample command line to run the script: >airtest run untitled.air --device Android:///手机设备号 --log log/.
  For more information on using the command line to run the script, please refer to the documentation .
• When using AirtestIDE run the script automatically generates a usable command line "Log View window" can be for your reference.
  "D:\AirtestIDE-path\AirtestIDE" runner "D:\script-path\untitled.air" --device Android://127.0.0.1:5037/5PZTQWQOGES8RWUG --log "C:\Users\username\AppData\Local\Temp\AirtestIDE\scripts\aa8c71acdfa70c3068b862cb42ffb8dc"

Device is connected

• At the command line run time, if passed in similar --device Android:///such device parameters, the script during initialization will automatically connect the corresponding device, you do not need to write additional code to connect up.
• If the device is not connected at the time of initialization, the script code may be used connect_deviceto connect to the device interface.
• Airtest a script attached to support multiple devices simultaneously, using set_currentthe interface can be switched in a plurality of devices, device()the interface can obtain the equipment currently in use.

Click simulation

Airtest as automated testing framework, the simulation of a human operator, common interfaces are:

• touch Click on a location, you can set position is clicked, the number, duration and other parameters hold down
• swipe Sliding from one position to another position
• text Enter the contents of the specified input method invocation
• keyevent Enter a key response, such as the enter key, the delete key
• wait Wait a specified picture element occurs
• snapshot Cut a picture of the current screen
• other

See this core API documentation , API appear in this document are the pages where cross-platform API, because we were in the first line of code airtest.core.apiin the interface to all importcome in, so the API can be invoked directly in code like such:

from airtest.core.api import *
touch((x, y))

In many interfaces, support incoming Templatepicture object as a parameter at run time would be to click on the location of the picture on the screen, like this:

# 等价于 touch((x, y)), (x, y)是图片所在的中心点
touch(Template(r"tpl1556019871196.png", record_pos=(0.204, -0.153), resolution=(1280, 720)))

Among them, Templatethe object is a picture category, Airtest will first try to find this picture can be matched position in the current screen, if found, will coordinate the operation to click, if found, will throw an exception identification. We will later on Templatebe covered in more detail picture category.

Platform-dependent interface

Just mentioned airtest.core.apiin the interface are cross-platform, but each specific interfaces supported platform may vary. For example, install the interface in the document 支持平台a column, only Android, meaning even the Windowstime of the device (ie, a Windows window), can not use this interface to install the application.

View a specific interface to support the case of a platform, please refer to the document directory 平台相关的APIto find the corresponding interface Depending on the platform, at the same time, also found under different platforms, there are some unique interfaces available for calls, For example, in the Android platform under:

from airtest.core.api import *
# Android平台下的touch接口支持额外的参数duration来控制点击屏幕的时长
# 翻阅airtest.core.android.android中的Android包含的touch方法来获取更多参数信息
touch((600, 500), duration=1)

# 在Android中，有一个平台独有的接口list_app可以列出所有安装过的应用
dev = device()  # 先获取到当前设备对象，这里的dev即是一个Android对象
print(dev.list_app())  # 然后就可以调用平台独有接口了

Assertion

Assertion is very important in the unit test code, it is recommended to use assert statements in our application under test script to determine whether the current state is a state we expected.

Airtest provided assert_existsand assert_not_existstwo interfaces to assert a picture exists or does not exist in the current screen.

At the same time, it also provides assert_equaland assert_not_equaltwo statements, asserting passed two equal or unequal values.

Second, how to use Python scripts in Airtest

AirtestIDE in the new script, it is possible to directly create a .pyscript file, but before creating a settings window will pop up, asked to fill in some of the specified parameters.

We find out about auto_setupthe interfaces will know that these parameters is to pass it, and then run the environment initialization Airtest used. Therefore, a pure .pyinitialization code of the script may look like this:

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",
    ])

# do something
# touch((x, y))

Code above means that, when  python xxx.py run in this document, without any command line parameters automatically using  auto_setup this interface to the relevant parameters of airtest initialized. So only need to write a script py, will be able to fill in the parameters specified by direct  python xx.py command to run the script.

Meanwhile, the original traditional  airtest run xx.air –-devices Android:/// command-line mode of operation will not be affected as long as the script detects an incoming command-line parameters (ie, code if not cli_setup()judgment), it is still a priority to use command-line parameters to initialize Airtest environment.

Of course, you master the API, you can also call Airtest API in your own Python scripts based on actual demand, the same third-party Python libraries using normal methods.

Third, the picture type Templateparameters Introduction

In AirtestIDE, the statement with the screenshot is able to demonstrate the corresponding picture, we know that this statement is to facilitate the use of what shots. In the editor, click the right mouse button menu 图片/代码模式切换, you can edit the current window code switch to plain text code, then we will see a touch(图片)such a statement might become this format:

touch(Template(r"tpl1556019871196.png", record_pos=(0.204, -0.153), resolution=(1280, 720)))

TemplateThat Airtest package picture category, will go running to read this picture, then find the coordinates of the points most in line with this picture in the current picture, and finally execute touchclick.

In the mid-section of Figure AirtestIDE, by default comes with three parameters, the first parameter is the name of the picture, and the second record_posrecorded the interception when this picture, its location, the third resolutionrecord is the interception of the picture, the current screen resolution.

• record_posThe effect is that you can make Airtest first search in the vicinity of the location at the time of the recording during playback script, if no eligible Picture of the expanded search range to the entire screen. This can enhance the look of the picture speed and accuracy.
• resolutionThe record is the resolution of the screen, if the playback script, Airtest on the resolution of the current picture will be scaled in accordance with a certain proportion on different devices, to facilitate the resolution of cross-matching picture.
• Although the direct use a picture path to initialize a Templateclass, it is also able to run code, but in order to be able to adapt more resolution of the device, as well as to enhance the image search rate, it is recommended you try to fill in the parameters. AirtestIDE taken image will automatically generate the corresponding parameters, if not satisfied with the image taken, may be used picture editor function further modified image.

In addition to these three parameters, but also support more image parameters, image recognition threshold during operation, the clicked location and whether gradation modification. Wherein the threshold image matching thresholdvalue and image recognition success rate is closely related to, read the documentation for more details.

Global image recognition CI

In the previous section, we introduce the class template image Templateparameters, and when we modify those parameters, corresponding only that picture will take effect, for example:

touch(Template(r"tpl1556019871196.png", threshold=0.9)

In this line of code, we will identify a picture of the threshold value thresholdis set to 0.9, meaning that when the identification result of the credibility of greater than or equal to 90%, we just think this image recognition matches, is a fairly strict set .

When if we want to be able to extend this to set all picture of the entire script, one by one, do not want to modify the code for each picture, we can consider changing global configuration Airtest to achieve this requirement:

from airtest.core.api import *
# airtest.core.api中包含了一个名为ST的变量，即为全局设置
ST.THRESHOLD = 0.8

# 未指定图片threshold，默认使用ST.THRESHOLD中的0.8
touch(Template(r"tpl1532588127987.png", record_pos=(0.779, 0.382), resolution=(407, 264)))

# 手工指定图片threshold，以图片设置的0.6为准
touch(Template(r"tpl1532588127987.png", record_pos=(0.779, 0.382), resolution=(407, 264), threshold=0.6))

There are more customizable global configuration items, please see the script global configuration document describes the page to get more configuration items.