II. Airtest API Documentation

1.Preface

In the previous AirtestIDE user manual, we mainly introduce how to use the automatic recording or auxiliary recording functions of the IDE to write Airtest scripts. However, for more complex Airtest scripts, we recommend that you use the Airtest API documentation and access more APIs to help achieve more complex automation operations.

Opening the official documentation of Airtest APIs, we can see from the navigation pane on the left that it includes a quick start guide for Airtest, as well as cross-platform and platform-specific APIs.

In the following text, we will provide a detailed introduction on how to use this API document.

2.Quick Start Guide for Airtest

By reading this module of the documentation, we can take a quick look at Airtest's supported platforms and some simple examples. (This is a just brief guide on Airtest scripts, and for more detailed information, it is recommended to read the Introduction to Airtest in this documentation.)

3.Cross-Platform Core APIs

This section introduces various cross-platform APIs of Airtest, which are also the core APIs of Airtest:

1) About "supported platforms"

Under this module, we can check the supported platform of the APIs, for example:

• touch API supports Android, iOS, and Windows.
• start_app API supports Android and iOS.
• clear_app API only supports Android.

The supported platforms refer to the platforms on which the API can run. For example, if the touch API is supported on three platforms, it means that this PAI can run on Android devices, iOS devices, and Windows.

So it is very important to pay attention to the supported platforms of the APIs, because Airtest provides cross-platform APIs as well as platform-specific APIs. If you use the API on an unsupported platform, it will inevitably lead to errors. For example, clear_app only supports the Android platform, so if you accidentally use it on the iOS platform, an error will occur.

2) About "parameters"

In addition to the supported platforms of the core APIs, we also need to pay attention to the parameters.

For example, when we were recording the script, we all knew that there was an image in the touch API. Does this mean that only one image can be passed in this API? To answer this question, we need to check its parameters in the API documentation:

According to the parameters of this API, we can not only pass in an image to touch, but pass in an absolute coordinate as well, similar to touch([100,100]). We can even set the number of clicks. For example, if we want to double-click, we can set times=2. In addition, we can also set some platform-related parameters. Knowing the parameters of the APIs can help achieve more operations.

3) About "return value"

Sometimes we also need to pay attention to the return values of APIs. For example, if we want to obtain the matching coordinates of a certain image on the current screen, what should we do? By checking the return values of various APIs, we can see that several APIs can help us do it:

Another example, if we want to touch a picture if it exists, or perform other operations if it doesn't, we can find the appropriate API by checking their return values:

If exists (image):
 touch(image)
else:
pass

It can be seen that with the exists API, if the target is found, the result will return the coordinates of the target. The if statement is met, and the target can be touched. If the target is not found, it will return false and the if statement is not met, so other operations will be executed.

4) About "example"

Furthermore, in the core API module of Airtest, we have provided example scripts for each API for reference:

4.Platform-Specific APIs

This module contains some platform-specific APIs, including APIs for Android, iOS, and Windows platforms:

1) Platform-specific APIs

Each platform has its own exclusive APIs. For example, the screen recording module is exclusive to the Android platform:

Sometimes, the cross-platform APIs cannot meet our needs for script writing. In this case, we can check the platform-specific APIs to see if there are any of them that meet our requirements.

2) Parameters of platform-specific APIs

For some APIs, when they are used as cross-platform, they only include a few general parameters. However, when used on the specific platform, they support additional parameters. For example, as cross-platform API, touch API supports two parameters: pos (the position of the click) and times (the number of clicks). But in the Android-specific module, it also supports an additional parameter: -duration (the duration of the click).

5.Search in the API Documentation

When writing Airtest scripts, we should make good use of the search function in the API documentation. When you encounter any question, you can easily find the solutions by searching in the API documentation.

For example, now you already understand how to touch/click on an image and want to know how to implement double-clicking. In this case, you can search for touch in Airtest's API documentation, starting with the core API module.

Then you will find that a cross-platform touch API supports setting the number of clicks:

So, all you need to do is pass in times=2 to this touch, and double-clicking will be achieved. What if you want to implement long touch, like clicking for 2 seconds or a longer time? We have already checked the core API of touch and no parameter can achieve this effect. So, let's check the platform-specific module. Assuming we are on an Android device:

It can be seen that touch for the specific Android platform has an additional parameter of -duration, capable of receiving the duration of a click as input. Therefore, by passing in duration=2 or more seconds to touch, we can achieve the desired effect.