Airtest

Cross-Platform UI Automation Framework for Games and Apps

Getting Started

• Cross-Platform: Airtest automates games and apps on almost all platforms.
• Write Once, Run Anywhere: Airtest provides cross-platform APIs, including app installation, simulated input, assertion and so forth. Airtest uses image recognition technology to locate UI elements, so that you can automate games and apps without injecting any code.
• Fully Scalable: Airtest cases can be easily run on large device farms, using commandline or python API. HTML reports with detailed info and screen recording allow you to quickly locate failure points. NetEase builds [Airlab](https://airlab.163.com/) on top of Airtest Project.
• AirtestIDE: AirtestIDE is an out of the box GUI tool that helps to create and run cases in a user-friendly way. AirtestIDE supports a complete automation workflow: create -> run -> report.

Get Started from Airtest Project Homepage

Supported Platforms

• Android
• iOS
• Windows
• Unity
• Cocos2dx
• Egret
• WeChat

Read more

Installation

This section describes how to install Airtest python library. Download AirtestIDE from our homepage if you need to use the GUI tool.

System Requirements

• Operating System:
  • Windows
  • MacOS X
  • Linux
• Python2.7 & Python3.3+

Installing the python package

Airtest package can be installed directly from Pypi. Use pip to manage installation of all python dependencies and package itself.

pip install -U airtest

You can also install it from Git repository.

git clone https://github.com/AirtestProject/Airtest.git
pip install -e airtest

Use -e here to install airtest in develop mode since this repo is in rapid development. Then you can upgrade the repo with git pull later.

Documentation

You can find the complete Airtest documentation on readthedocs.

Example

Airtest provides simple APIs that are platform independent. This section describes how to create an automated case which does the following:

1. connects to local android device with adb
2. installs the apk application
3. runs application and takes the screenshot
4. performs several user operations (touch, swipe, keyevent)
5. uninstalls application

from airtest.core.api import *

# connect an android phone with adb
init_device("Android")
# or use connect_device api
# connect_device("Android:///")

install("path/to/your/apk")
start_app("package_name_of_your_apk")
touch(Template("image_of_a_button.png"))
swipe(Template("slide_start.png"), Template("slide_end.png"))
assert_exists(Template("success.png"))
keyevent("BACK")
home()
uninstall("package_name_of_your_apk")

For more detailed info, please refer to Airtest Python API reference or take a look at API code

Basic Usage

Airtest aims at providing platform independent API, so that you can write automated cases once and run it on multiple devices and platforms.

1. Using connect_device API you can connect to any android/iOS device or windows application.
2. Then perform simulated input to automate your game or app.
3. DO NOT forget to make assertions of the expected result.

Connect Device

Using connect_device API you can connect to any android/iOS device or windows application.

connect_device("platform://host:port/uuid?param=value&param2=value2")

• platform: Android/iOS/Windows…
• host: adb host for android, iproxy host for iOS, empty for other platforms
• port: adb port for android, iproxy port for iOS, empty for other platforms
• uuid: uuid for target device, e.g. serialno for Android, handle for Windows, uuid for iOS
• param: device initialization configuration fields. e.g. cap_method/ori_method/…
• value: device initialization configuration field values.

see also connect_device.

Connect android device

1. Connect your android phone to your PC with usb
2. Use adb devices to make sure the state is device
3. Connect device in Airtest
4. If you have multiple devices or even remote devices, use more params to specify the device

# connect an android phone with adb
init_device("Android")

# or use connect_device api with default params
connect_device("android:///")

# connect a remote device using custom params
connect_device("android://adbhost:adbport/1234566?cap_method=javacap&touch_method=adb")

Connect iOS device

Follow the instruction of iOS-Tagent to setup the environment.

# connect a local ios device
connect_device("ios:///")

Connect windows application

# connect local windows desktop
connect_device("Windows:///")

# connect local windows application
connect_device("Windows:///?title_re=unity.*")

Airtest uses pywinauto as Windows backend. For more window searching params, please see pywinauto documentation.

Simulate Input

Following APIs are fully supported:

• touch
• swipe
• text
• keyevent
• snapshot
• wait

More APIs are available, some of which may be platform specific, please see API reference for more information.

When using these general APIs, Airtest will automatically call the corresponding operations according to the current platform, such as the following code example:

from airtest.core.api import *  # import the general APIs such as touch/swipe/...

connect_device("Android:///")
touch((100, 100))

connect_device("Windows:///")
touch((100, 100))

Airtest also provides some platform-specific APIs for each platform, which can be queried in the module API of each platform:

• general APIs: API reference
• Android: airtest.core.android.Android class
• Windows: airtest.core.win.Windows class
• iOS: airtest.core.ios.IOS class

>>> from airtest.core.api import *
>>> connect_device("Android:///")
>>> dev = device()  # get current device, which is an Android object
>>> print(type(dev))
<class 'airtest.core.android.android.Android'>
>>> dev.get_top_activity()  # use Android ADB to get the top activity
('com.google.android.apps.nexuslauncher', '.NexusLauncherActivity', '2720')

Make Assertion

Airtest provide some assert functions, including:

• assert_exists
• assert_not_exists
• assert_equal
• assert_not_equal

When assertion fails, it will raise AssertsionError. And you will see all assertions in the html report.

Running .air from CLI

Using AirtestIDE, you can easily create and author automated cases as .air directories. Airtest CLI provides the possibility to execute cases on different host machine and target device platforms without using AirtestIDE itself.

Connections to devices are specified by command line arguments, i.e. the code is platform independent and one automated case can be used for Android, iOS or Windows apps as well.

Following examples demonstrate the basic usage of airtest framework running from CLI. For a deeper understanding, try running provided automated cases: airtest/playground/test_blackjack.air

run automated case

# run automated cases and scenarios on various devices
> airtest run "path to your .air dir" --device Android:///
> airtest run "path to your .air dir" --device Android://adbhost:adbport/serialno
> airtest run "path to your .air dir" --device Windows:///?title_re=Unity.*
> airtest run "path to your .air dir" --device iOS:///
...
# show help
> airtest run -h
usage: airtest run [-h] [--device [DEVICE]] [--log [LOG]]
                   [--recording [RECORDING]]
                   script

positional arguments:
  script                air path

optional arguments:
  -h, --help            show this help message and exit
  --device [DEVICE]     connect dev by uri string, e.g. Android:///
  --log [LOG]           set log dir, default to be script dir
  --recording [RECORDING]
                      record screen when running
  --compress
                      set snapshot quality, 1-99
  --no-image [NO_IMAGE]
                      Do not save screenshots

generate html report

> airtest report "path to your .air dir"
log.html
> airtest report -h
usage: airtest report [-h] [--outfile OUTFILE] [--static_root STATIC_ROOT]
                      [--log_root LOG_ROOT] [--record RECORD [RECORD ...]]
                      [--export EXPORT] [--lang LANG]
                      script

positional arguments:
  script                script filepath

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     output html filepath, default to be log.html
  --static_root STATIC_ROOT
                        static files root dir
  --log_root LOG_ROOT   log & screen data root dir, logfile should be
                        log_root/log.txt
  --record RECORD [RECORD ...]
                        custom screen record file path
  --export EXPORT       export a portable report dir containing all resources
  --lang LANG           report language

get case info

# print case info in json if defined, including: author, title, desc
> python -m airtest info "path to your .air dir"
{"author": ..., "title": ..., "desc": ...}

Import from other .air

You can write some common used function in one .air script and import it from other scripts. Airtest provide using API to manage the context change including sys.path and Template search path.

from airtest.core.api import using
using("common.air")

from common import common_function

common_function()