II. Running Scripts Using Command Line¶
After the script is written, it can be run inside AirtestIDE or outside it through the command line.
1.Running Scripts Using AirtestIDE Command Line¶
Even if the local machine does not have a Python environment installed, as well as Airtest and Poco, we can still use the command line to run the script. The trick is to copy the command line displayed in the log window when running the script in AirtestIDE:
Copy the command line code generated by AirtestIDE when running the script and paste it into your command line terminal. Press the Enter key to run it.
Please note that using AirtestIDE command line to run scripts is a simple and fast way. However, if you want to execute scripts in batches or simultaneously, you may encounter efficiency issues. If you have a need for long-term or batch script execution, please install Airtest and Poco in your local Python environment to run the scripts. Details are in the following section.
2.Running Scripts Using Command Line in the Local Environment¶
Although it is very convenient to use AirtestIDE command line to run scripts, it is not suitable for more complex operations, for example, running multiple scripts on multiple phones with multiple command lines simultaneously. And some Python developers may need to use other powerful Python third-party libraries in their scripts. Therefore, we recommend installing Airtest and Pocoui in the local Python environment and then running scripts using the command line. As for how to deploy Python environment, we have already provided a detailed introduction on it in the previous two sections and will not repeat it here. After deploying the local Python environment, we can run our automation scripts in it without relying on AirtestIDE.
1) Examples of running scripts using command line¶
We can use the command airtest run + script path to run Airtest scripts. Here's an example:
>airtest run untitled.air --device Android:/// device string --log log/
>python -m airtest run untitled.air --device Android:///device string --log log/
These two command lines have the same effect. With them, we run a script called untitled.air with Airtest, passing in two parameters: --device and --log, which are respectively the mobile device string and the log output directory.
2) Introduction to parameters of airtest run command¶
The mandatory parameter for the airtest run command is the path of the script. Other optional parameters include:
- --device: specifies the device string
- --log: specifies the log output directory
- --compress: specifies the snapshot precision, with a value range of [1, 99]. The higher the precision, the clearer the snapshot.
- --recording: sets to record the running process of the script (With Airtest version greater than 1.1.6, you can set the recording file name after this parameter.)
- --no-image: sets not to take snapshots during the script running process (added in airtest1.1.7)
We can also refer to the Airtest-running-air-from-cli documentation to learn more about these parameters.
More examples of command lines for running scripts:
# Disable taking snapshots during script execution
> airtest run test.air --device Android:/// --log logs/ --no-image
# Set the snapshot accuracy during the script execution process to 90
> airtest run test.air --device Android:/// --log logs/ --compress 90
# Set to record screen during the running process and save the recording as 123.mp4.
>airtest run test.air --device Android:/// --log logs/ --recording 123.mp4
3) Introduction to device string¶
The --device parameter used in the previous command line takes in a device string. Taking an Android device as an example, its string is made up as follows:
Android://<adbhost[localhost]>:<adbport[5037]>/<serialno>
Among them, adbhost is the IP address of the host where the adb server is located, with the default being 127.0.0.1 on the local machine. The adb port is default to 5037, and serialno is the serial number of the Android phone. For more information about ADB, please refer to the ADB documentation. The device string here can be of an Android device, an iOS device, and a Windows window, etc.
① Android device string¶
# If nothing is filled in, the first mobile phone in the current connection list will be automatically selected.
Android:///
# Connect to a mobile device with the ID 79d03fa, connected to the default port of this machine.
Android://127.0.0.1:5037/79d03fa
# Use the ADB on this machine to connect to a remote device that has been connected via adb connect. Note that 10.254.60.1:5555 is the serial number.
Android://127.0.0.1:5037/10.254.60.1:5555
In the Common Connection Issues for Android, we mention that some devices uniquely require special connection options such as use ADB orientation or use javacap to connect to the phone. For these devices, such parameters are needed to be appended to the device string when running scripts with the command line:
# The emulator is connected and the `Use javacap` mode is selected.
Android://127.0.0.1:5037/127.0.0.1:7555?cap_method=JAVACAP
# After all options are checked, use && to connect multiple parameter strings.
Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP&&ori_method=ADBORI&&touch_method=ADBTOUCH
Note: If the characters like ^ < > | & appear in the command line, they may need to be escaped in order to take effect. Therefore, if you need to write && in the connection string, you need to rewrite it as ^&^& in Windows, by adding a symbol of ^ to escape it, as follows:
# --device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP&&ori_method=ADBORI Not available on Windows
--device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP^&^&ori_method=ADBORI # Adding ^ escape for Windows command line
--device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP\&\&ori_method=ADBORI # Adding \ escape for Mac command line
Not escaping special characters normally causes the command line to be truncated. For example, when running a script using the command line, users often apply commands of this type:
airtest run test.air --device Android://127.0.0.1:5037/79d03fa?cap_method=JAVACAP&&ori_method=ADBORI --log logs/
If you run this command on Windows terminal, it will prompt do not save log. You will find it strange because you have already used the --log parameter to specify the log path in this command. Why does it still prompt you that the log is not saved? Well, it's because this command contains the special character & which is not escaped and causes the command to be truncated. Therefore, please don't forget to escape the special characters.
② iOS device string¶
# Connect an iOS phone
iOS:///127.0.0.1:8100
③ Windows window string¶
# Connect to a Windows window, with the handle being 123456
Windows:///123456
# Connect to a Windows window, with the window name matching a certain regular expression
Windows:///?title_re=Unity.*
# Connect to Windows desktop, without specifying any windows
Windows:///
It should be noted that the connection to a Windows window uses the pywinauto library. By default, AirtestIDE uses the window handle that is already connected to the IDE to establish the connection. It can be expected that if the window is closed and opened again, the handle may change. Therefore, our connection string supports using connect API of pywinauto to connect to the window. This document provides more details on how to fill in the parameters of the connection string: Windows:///?name=value.
Note
If the device string you write by yourself fails to connect to the device but can work normally in AirtestIDE, you can consider running the script once in AirtestIDE and then copy the parameters in the --device Android:/// in the command line generated during runtime. This approach can help greatly avoid an incorrect input of device string.
4) Recording the script running process¶
When running a script on an Android device, we can add a --recording parameter in the command line to enable Airtest to automatically record the screen during the script running process. (After running, the recording file will be saved in the log folder by default, named recording_serialno).
airtest run "D:\test\Airtest_example.air" --device android://127.0.0.1:5037/emulator-5554?cap_method=MINICAP_STREAM^&^&ori_method=MINICAPORI^&^&touch_method=MINITOUCH --log "D:/test\41f68fdf265d8c13998d0a1a7b992889" --recording
Additionally, Airtest1.1.6 supports adding a file name after the --recording parameter to name the screen recording file. For example, --recording test.mp4. If there are multiple phones running, the file will be named as phone name_test.mp4. The following example uses --recording 123.mp4 to specify the file name as 123.mp4:
airtest run "D:\test\untitled.air" --device android://127.0.0.1:5037/emulator-5554 --log "D:/test\6fe87b11ca1fc75ebe670439f20fabfc" --recording 123.mp4
Also, it should be noted that the screen recording file name must end with .mp4!