VIII. Airtest Script Global Settings¶

1.Global Settings for Scripts¶

In airtest.core.settings, some global default attributes are provided. Here is the list of some of the common ones and their default values:

LOG_DIR = None
LOG_FILE = "log.txt"
RESIZE_METHOD = staticmethod(cocos_min_strategy)
CVSTRATEGY = ["mstpl", "tpl", "surf", "brisk"]
THRESHOLD = 0.7 # [0, 1]
THRESHOLD_STRICT = 0.7 # [0, 1]
OPDELAY = 0.1
FIND_TIMEOUT = 20
FIND_TIMEOUT_TMP = 3
PROJECT_ROOT = os.environ.get("PROJECT_ROOT", "") # for using other script
SNAPSHOT_QUALITY = 10 # 1-100
IMAGE_MAXSIZE = os.environ.get("IMAGE_MAXSIZE", None)
SAVE_IMAGE = True

2.Method for Global Attribute Settings¶

To change the value of the settings above, simply write it in the script as follows:

from airtest.core.api import *
# Airtest.core.api contains a variable named ST, which is the global setting.

ST.THRESHOLD = 0.8

# If the image threshold is not specified, the default value of 0.8 in ST.THRESHOLD will be used.

touch(Template(r"tpl1532588127987.png", record_pos=(0.779, 0.382), resolution=(407, 264)))

# Manually specify the image threshold to the image setting of 0.6

touch(Template(r"tpl1532588127987.png", record_pos=(0.779, 0.382), resolution=(407, 264), threshold=0.6))

3.Introduction to Attribute Values¶

1) Log content settings: LOGFILE, LOGDIR¶

LOGFILE is used to customize the name of the txt document that records the log content. LOGDIR is used to customize the storage path of the log content, as shown below:

from airtest.core.settings import Settings as ST
from airtest.core.helper import set_logdir

ST.LOG_FILE = "log123.txt"
set_logdir(r'D:\test\1234.air\logs')

auto_setup(__file__)

# Several test case scripts are omitted here.

2) Resolution adjusting method: RESIZE_METHO¶

When using devices with different resolutions for image recognition, it may result in poor recognition success rates. Therefore, Airtest provides a default resolution adjusting method (using the default scaling rules of the Cocos engine), and here is the code:

The best way to improve the recognition accuracy of a 2D game is to clearly specify the resolution adjusting method for the game. For example, write it directly at the beginning of the .air script file like this:

from airtest.core.api import *

def custom_resize_method(w, h, sch_resolution, src_resolution):
    return int(w), int(h)

# Replace the default RESIZE_METHOD
ST.RESIZE_METHOD = custom_resize_method

The above code specifies a custom scaling rule: directly return the original value, regardless of screen resolution, and all UI is not scaled (some games use this strategy). The RESIZE_METHOD here, namely the custom_resize_method we define, inputs the following parameters:

w, h # The width and height of the UI image recorded
sch_resolution # The screen resolution during recording
src_resolution # The screen resolution during playback

Output:

The width and height of the UI image during playback

To customize your RESIZE_METHOD, you only need to know the scaling rules of the game being tested and implement them through code in the custom_resize_method. This can greatly improve the success rate of image recognition on devices with different resolutions.

3) Image recognition algorithm settings: CVSTRATEGY¶

CVSTRATEGY is used to configure the image recognition algorithm for Airtest. By default, CVSTRATEGY = ["mstpl", "tpl", "surf", "brisk"]. When searching for an image, Airtest will execute the algorithms in the order specified by this setting until a recognition result that meets the set threshold is found, or it will continue to search in a loop according to this algorithm order until it times out. You can customize Airtest's image recognition algorithm as follows:

from airtest.core.settings import Settings as ST

# During script execution, recognition will be performed in this algorithm order until "a recognition result that meets the set threshold is found" or "recognition times out".
ST.CVSTRATEGY = ["tpl", "sift","brisk"]

P.S. For an introduction to the various image recognition algorithms in Airtest, we recommend reading the article. Learn to Choose the Right Image Recognition Algorithm in 3 Minutes Introduction of the New Image Recognition Algorithm mstpl

4）Image thresholds: THRESHOLD, THRESHOLD_STRICT¶

THRESHOLD and THRESHOLD_STRICT are both thresholds for image recognition. After version 1.1.6 of Airtest, all APIs that use image recognition use THRESHOLD as the threshold. Its default value is 0.7, with a range of [0,1].

When performing image matching, a match is only considered successful when the confidence of the recognition result is greater than the threshold value.

In addition to modifying the global image recognition threshold, we also support modifying the threshold for a single image. It should be noted that if the threshold for an image is not set separately, the global threshold THRESHOLD will be used by default. An example is shown below:

from airtest.core.settings import Settings as ST

# Set the global threshold value to 0.8
ST.THRESHOLD = 0.8

# Set the threshold value of a single image to 0.9
touch(Template(r"tpl1607424190850.png", threshold=0.9, record_pos=(-0.394, -0.176), resolution=(1080, 1920)))

Before Airtest 1.1.6, the image threshold used by assert_exists was THRESHOLD_STRICT. Therefore, if you are using versions before 1.1.6 and want to modify the image threshold of assert_exists, you need to set the value of THRESHOLD_STRICT.

5) Time interval between steps: OPDELAY¶

In the script, there is a time interval between each step of operations, which is set by default using OPDELAY. The default value of OPDELAY is 0.1, which means waiting for 0.1 seconds after each operation. Scaling it up can make a longer pause for each operation, preventing the situation where the script runs so fast that the operation fails to be completed.

6) Timeout duration for queries: FIND_TIMEOUT, FIND_TIMEOUT_TMP¶

During each image search, if the search fails, a snapshot-search loop will be performed until a timeout occurs. You can set the duration using FIND_TIMEOUT. The default duration is 20 seconds.

Additionally, we also offer FIND_TIMEOUT_TMP, which is set to 3 seconds by default. These two settings are for different snapshot APIs.

The APIs using FIND_TIMEOUT to set the timeout duration for image search include:

touch
double_click
swipe (When this API is used to swipe from one image to another, only the first image uses FIND_TIMEOUT.)
wait (This API supports passing in a timeout parameter directly. If no timeout parameter is specified, FIND_TIMEOUT is used as the default timeout duration)
assert_exists Other APIs with lower requirements for image searching uese FIND_TIMEOUT_TMP with shorter duration:
swipe (If the second parameter is passed with an image, it will use a shorter search time.)
exists
assert_not_exists If you want to modify the global timeout duration for image searches, please pay attention to which value needs to be modified. Example of modification:

``` from airtest.core.settings import Settings as ST

# Set the global timeout duration to 60s ST.FIND_TIMEOUT = 60 ST.FIND_TIMEOUT_TMP = 60

# Set the timeout duration for a single wait statement wait(Template(r"tpl1607425650104.png", record_pos=(-0.044, -0.177), resolution=(1080, 1920)),timeout=120) ```

7) Project root directory: PROJECT_ROOT¶

By setting a default project root directory with PROJECT_ROOT, you can enable the using API to search for other subscripts in the current root directory without filling out the full path, making it more convenient for scripts to call each other.

For example, we create a script named test1.air, with the actual path being /User/test/project/test1.air.

from airtest.core.api import *

def test():
    touch("tmp.png")

Another script, main.air, in the same directory can import the test in it with the following code:

from airtest.core.api import *

ST.PROJECT_ROOT = "/User/test/project"
using("test1.air")
from test1 import test

In addition, the auto_setup() API can also take the project root directory as an argument:

auto_setup(__file__, project_root="/User/test/project")

8) Snapshot compression quality: SNAPSHOT_QUALITY¶

SNAPSHOT_QUALITY is used to set the global snapshot compression quality. It should be noted that it sets the quality of the snapshot displayed in Airtest reports, not the actual quality of the one captured in the script. The default value is 10, and the valid range is [1, 100]. The higher the value, the higher the snapshot quality and the clearer the image. Here is an example:

from airtest.core.settings import Settings as ST

# Set the global snapshot quality to 90

ST.SNAPSHOT_QUALITY = 90

In addition, we can define the compression quality of a single snapshot, for example:

# Set the compression quality of a single snapshot to 90 and leave the rest to use the global compression quality.

snapshot(quality=90)

9) Snapshot size: IMAGE_MAXSIZE¶

In Airtest 1.1.6, a new setting was added to specify the maximum size of a snapshot: ST.IMAGE_MAXSIZE. If it is set to 1200, the saved snapshot size will not exceed 1200 in width or height, which helps to reduce the size of the snapshot. For example:

from airtest.core.settings import Settings as ST

# Set the global snapshot size to not exceed 600*600. If not set, the default is the original image size.

ST.IMAGE_MAXSIZE = 600

# If not set separately, it will default to the value of the global variable in ST, which is 600*600.

snapshot(msg="test12")

# Set the maximum size of a single snapshot to not exceed 1200*1200

snapshot(filename="test2.png", msg="test02", quality=90, max_size=1200)

10）Save the snapshot of the running process: SAVE_IMAGE¶

By default, snapshots of the steps are saved during the runtime for display in the report's overview and step details. However, starting from Airtest 1.1.7, the settings have added a new configuration, ST.SAVE_IMAGE, which is set to True by default. If set to False, snapshots will not be saved until this value is set to True again. For example:

from airtest.core.api import *
# Temporarily disable snapshot
ST.SAVE_IMAGE = False
touch((100, 100)) # This statement will not save the current screen image.

# Enable snapshot 
ST.SAVE_IMAGE = True
touch((100, 100))

(touch with the snapshot not saved)

(touch with the snapshot saved)