5 minutes to get started with Airtest and Poco
Foreword
This document will demonstrate the use of the specific editor AirtestIDE of AirtestProject ,and we will use it to write the entire flow of the Airtest and Poco automation scripts.Newcomers are strongly encouraged to read from this document and use AirtestIDE to write scripts.
Introduction
AirtestIDE is a cross-platform UI automation test editor for games and apps.
- Automated scripting, one-click playback, report viewing,and easily implement automated test processes
- Support for Airtest framework based on image recognition,and suitable for all Android/iOS/Windows apps
- Support for Poco framework based on UI control search,and suitable for multiple platforms such as Unity3d, Cocos2d and Android/iOS App
- Ability to run on Windows and MacOS platforms
Please visit Official Website to view more features via video.
Through this tutorial, you will learn how to get started with automated testing (or write a script to play games automatically). Believe me, this process will be very enjoyable~
installation
At present, AirtestIDE provides two versions of Windows and Mac clients. Please download them from Official Website and it can be used after decompression.
Connecting device
AirtestIDE currently supports testing applications on Android/Windows/iOS,and the support for more platforms is under development.
Whether it's an Android/iOS phone or a Windows window, it's considered a device in Airtest, then we'll show you how to connect a device.
Connect to an Android phone
Connect your computer and Android phone via ADB,and you can start debugging your Android app. ADB is the official Android debugging tool provided by Google.And AirtestIDE relies on ADB to communicate with Android devices.
Open AirtestIDE and follow the steps below to connect:
- Open the phone
Settings - Developer Options - USB Debuggingswitch, refer to Android Official Document - Click on the
refresh ADBbutton in the AirtestIDE device panel and look at the connected device - If the device is not displayed, try
restart ADB,If not, refer to the FAQ documentation for troubleshooting. - After successfully seeing the device, click the corresponding device's
Connectbutton to initialize
Once the phone is connected successfully, you can see the mirror image of the phone screen in AirtestIDE and perform real-time operation.
If the phone connection fails, please refer to the FAQ documentation for troubleshooting.If it is still unsuccessful, please submit the phone model and AirtestIDE background error to Github Issue,and developers will fix it as soon as possible.Due to the serious fragmentation of Android phones, we are very grateful for your feedback to help this project do a better job.
Connect to Windows window
For the testing of Windows desktop programs, AirtestIDE can embed the measured window, which is convenient for script recording and debugging.
- Click the 'Windows-box game window' button in the AirtestIDE device panel.
- Move the mouse to the window of the tested program, a green border will be displayed, and the corresponding window will be framed.
- Click the left button to embed the corresponding window in AirtestIDE.
If the above method does not find the window of the tested program, you can also use the alternate embedding method.
Connect to an iOS phone
In order to connect to an iOS phone, you need to have a Mac computer with Xcode installed. The connection method can be found in this document.
Recording automation script
After connecting the device, we can start recording the automated test script.In the following content, we will use a Unity game app on an Android device to show you how to record a script.
Analog input
Let's start with the most commonly used simulated click.The meaning of a simulated click is to imitate your actions to click on a specific location on the device.
Based on image recognition
Currently we support the image recognition method to find the location you want to click and operate on it.This is based on the framework Airtest.
First we can see how to automatically record the script:click the `Record' button on the Airtest aux window on the left side of AirtestIDE, and the code will be automatically generated in the code window as you operate the phone on the device window.
Check it out now, click the Run button to run your first automated script!
If you feel that the icon generated by automatic recording is not accurate enough,you can also click on the touch button on the Airtest aux window and then select the exact icon on the device window. This will also automatically generate a touch statement.
Sliding is also a similar analog input operation:click the swipe button, select the exact icon on the device window as the starting point for the slide, and then click the end position for the slide.A swipe statement is automatically generated.
Other analog input API includes:
- text: text input
- keyevent: key input, including (HOME/BACK/MENU, etc.)
- sleep: wait
- snapshot: screen capture
Based on UI controls
If you find that image recognition is not accurate enough, you can use the method based on UI controls search to conduct automated testing.Unlike the Airtest just mentioned, this is the function implemented by the Poco framework.
Currently, Poco directly supports various game engines such as Unity3d, Cocos2d, Egret Engine, and Android/iOS native app.
For Android/iOS native apps, it is plugged in and can be used without accessing the SDK.But since the game engine uses a graphical interface such as OpenGL to render directly without using the Android native UI system, we need to communicate with the game's Runtime to get the entire UI structure.
We provide a very convenient SDK access method, click here to see a list of currently supported platforms and how to connect to poco for your project.
If your project uses an engine or platform that is not in the documentation, we also support self-expanding SDK.
In fact, within the NetEase game, we have supported multiple self-research engines such as Messiah/NeoX/Dream in this way.
Once the access is complete we can start. Start the game on your phone, then switch the mode to the corresponding engine type in the Poco Assist window in AirtestIDE, so you can see the entire UI structure.
Click the Record button.And when you operate your mouse, it will automatically generate the corresponding poco statement into the script editing window.
Similarly, you can view UI controls more precisely through the UI tree structure, double-click nodes to automatically generate Poco statements, or choose a better way to write.
Automatically recorded statements may not be able to adapt to all scenarios. Writing code with a more reasonable selector will usually enhance the robustness and readability of the entire automated script. This is a study.
After recording the script, you have to remember to run it and see the effect.
For the Android/iOS native app, you don't need to access the SDK to use it. For example, after connecting to the Android phone and switching the mode of the Poco auxiliary window to Android, you can see the entire UI tree structure.
Frame information
The above two UI recognition methods are based on two frameworks:
Both of these frameworks are Python third-party libraries developed by our team.In the actual project experience, we found that the cooperation between the two will get the best results.In the process of scripting, we often need to consult their API documentation.
Use Python syntax
The code recorded and run throughout AirtestIDE is based on the Python language.The Python syntax is simple and powerful, and there are many third libraries and tools.
For newbies, Python is very easy to get started.By learning the basic grammar you can write the logic statements needed in the automation script.
touch("开卡包.png")
if exists("奖励面板.png"):
for i in range(5):
Poco("奖励-%s" % i).click()
For veterans, you can use a variety of third-party libraries in AirtestIDE to make your automation scripts even more powerful.And by adding a PYTHONPATH setting, you can use the local python.exe file to run your script.
In addition to the statements provided in the auxiliary window, for more API documentation, you can check Airtest and Poco warehouse.
assertions
At this point, we already have a variety of analog input methods, with the logic control statement to make the phone move. There is one more important step in automated testing: Result Verification, then let's see how to declare assertions.
Verify UI interface
Recording method is similar to analog input.
assert_exists：assert that the image existsassert_not_exists：assert that the image does not exist
verify numerical value
Get attribute values via Poco,then handwrite code to make assertions
assert_equal: Assert equalityassert_not_equal: Assert unequality
For example
# ... After simulating the input and getting 20 points
value = Poco("Score button").attr("num")
assert_equal(value, 20, "get 20 points")
View test report
Once the script has finished running, you can click on the View Report button (shortcut Ctrl+L) to open the report page using the default browser.The report will show the content of each step, the screenshots of the actual execution process and the running results, so that it is convenient to see if the steps are executed successfully.
Command line interface
Now that you have learned automated testing.Next, you can use the command line interface to combine automated testing with continuous integration. What is continuous integration?
When the script is run in AirtestIDE, the run command will be printed in the LOG window.
You can use that command on the command line to start the test script without opening the IDE, for example:
"D:\Thunder download\AirtestIDE\AirtestIDE" runner "D:\AirtestIDE_2018-01-24_83\untitled.air" --device Android://127.0.0.1:5037/F8UDU16409004135 --log "C:\Users\gzliuxin\AppData\Local\Temp\AirtestIDE\scripts\cdfc40e8c297b6ad88e09de64d8bafa3"
With AirtestIDE you can easily record test scripts and save them as .air scripts. Please note that there should not be too much content in an .air script.You can organize your scripts with good script naming and directory structure, and cover all test points.
You can also run tests on different devices on different computers. You will need to run the .air script from the command line.For products released on multiple platforms, flexible use of cross-platform API and command lines also allows the same set of test scripts to run on Android and Windows.
Inside the Netease game，our large games usually have hundreds of test scripts that cover common gameplay tests.Each week, these hundreds of scripts are run on 200 phones for compatibility testing.
