# 1.2 Test on an Android phone ## How to connect an Android phone For information about how to connect an `Android` phone, check the [Device Connection Document](../1_online_help/connecting_devices.html),Please refer to the [FAQ](../3_faq/android_connection_new.html) to get more help if you have any problems during the connection. A successful connection to the phone is indicated by AirtestIDE displaying the phone screen in the 'Devices' window. ### Running the scripts on the phone In this section, you can learn how to run scripts on the phone. Check the first section of this quick start guide for more information about how to write scripts. In order to run scripts, just click the "Run" button or press the shortcut key `F5`. The script should start running. The log window at the bottom will print out the command line executed by the script, it should look simmilar to this: ``` "D:\AirtestIDE\AirtestIDE" runner "untitled.air" --device Android://127.0.0.1:5037/F8UDU16409004135 --log "D:\log" ``` The `--device Android://127.0.0.1:5037/F8UDU16409004135` parameter, tells `Airtest` the serial number of the local connected phone we would like to use `F8UDU16409004135`. Check the 'Running Scripts' section of the documentation for more details on other commands. In the connection string `Android://:/`, Adbhost is the ip of the host where the adb server is located, the adb port default is 5037, and serialno is the serial number of the android phone. For more information on the aspects of adb, please refer to the documentation.[developer.google](https://developer.android.com/studio/command-line/adb)。 Alternatively, it is possible to connect to the phone through code via script using the `connect_device` interface: ```python from airtest.core.api import connect_device # Incoming connection string dev = connect_device('Android://:/') ``` ### Multi-machine collaboration Airtest allows to connect multiple devices at the same time. This could be needed in order to write a "multi-machine collaboration" script. If we are currently using AirtestIDE to write scripts and connect to multiple phones at the same time, AirtestIDE will automatically add multiple `--device` parameters when running the script, no additional operations are required. Otherwise, you can use the bellow `connect_device` statement directly in the script to pass in the phones connection string information. ```python from airtest.core.api import connect_device dev1 = connect_dev("Android://127.0.0.1:5037/serialno1") # Connect to the first phone dev1 = connect_dev("Android://127.0.0.1:5037/serialno2") # Connect to the second phone # At this time, the device list is [dev1, dev2], and the incoming number 0 switches the currently operated mobile phone to the first station. set_current(0) # Switch the current phone to the phone with the serial number of serialno2 set_current("serialno2") ``` ## Mobile device related operations On the Android device, you may need to get some device/App related information, or execute the `ADB` command and get the output. In `Airtest`, in addition to some common interfaces, we also encapsulate a number of `Android` unique interfaces to facilitate scripts running on the `Android` platform. For example, we might want to start the APP under test at the beginning of the script: ```python from airtest.core.api import * start_app('package_name') ``` The `start_app` interface used in this sample code is a generic interface for the platform, that is, it can also be used on the `Windows` and `iOS` platforms. The specific supported platform information can be found in the [start_app interface documentation](https://airtest.readthedocs.io/en/latest/all_module/airtest.core.api.html#airtest.core Get the `Platforms` field in .api.start_app). The line `from airtest.core.api import *` is needed to introduce the `API` defined in `airtest.core.api` and use `Airtest` packaged in this common `API`. **Note:** AirtestIDE automatically adds this line when creating a new script. Please do not delete it, otherwise the airtest api will not be called and the commands will not work! ### Android device interface In the previous section it was mentioned that `connect_device` can be used to connect to the phone and get the connected `Device` object. This can also be retrieved through the `device()` interface. The next example prints a list of all installed apps on the `Android` device that is **currently connected**: ```python # Get the currently connected phone dev = device() # Print out the app list print(dev.list_app()) ``` The `list_app` command used in the example comes from the package `airtest.core.android.android`. This is `Airtest`'s unique interface of `Android` and has encapsulated a lot of useful operations for `Android` devices, such as `install_app`, `get_top_activity()`, etc., For more, refer to the [`airtest.core.android.android` documentation](http://airtest.readthedocs.io/zh_CN/latest/all_module/airtest.core.android.android.html) . ### ADB instruction call While writting test scripts for `Android`'s platform, sometimes it is required to input some `ADB` instructions. A module such as `subprocess` might be convenient when calling the `ADB` command in `Python` scripts. However, within the `Airtest Project` script, calling the `ADB` directive is very simple: ```python # Execute instructions on the current device adb shell ls print(shell("ls")) # Perform adb instructions on specific devices dev = connect_device("Android:///device1") dev.shell("ls") # Switch to a device and execute the adb instruction set_current(0) shell("ls") ``` ## Testing Android native apps Poco supports UI hierarchy recognition directly for any **Android native app** (non-game engine, non-webview), in the same way as poco does on other platforms. For webview-based applications that are special (such as WeChat applets or browsers), see [webview app using poco guidelines]() ### Preparation Select Android mode in AirtestIDE's `Poco Assistant` panel, which will automatically install PocoService.apk, and the corresponding test apk into the phone and start PocoService. This apk is used to perform a crawling through the UI hierarchy of the app. Android's interface hierarchy Service will take a moment to show the UI hierarchy in the AirtestIDE interface. Click on any node to see all its properties in the `Log` panel and box out the corresponding location in the device screen. The development environment for Android native application testing is now ready, and a simple test can begin such as the one in the following example: ### Example Click here to download [Example App(calculator)](http://top.gdl.netease.com/poco-res/poco-demo-android-native-app.zip) and install the app on your phone beforehand. **First of all**, you must initialize the `poco` instance to use the `poco` methods for object selection and manipulation. The following example demonstrates a simple function: Click on the calculator interface to implement a `1+1=2` operation verification. For more poco usage and examples, see [poco tutorial](http://poco.readthedocs.io/en/latest/source/doc/poco-example/index.html) ```python from poco.drivers.android.uiautomation import AndroidUiautomationPoco poco = AndroidUiautomationPoco() poco('com.google.android.calculator:id/digit_1').click() poco('com.google.android.calculator:id/op_add').click() poco('com.google.android.calculator:id/digit_1').click() poco('com.google.android.calculator:id/eq').click() result = poco('com.google.android.calculator:id/formula').get_text() self.assertEqual(result, '2', '1+1=2 ^^') ``` If multiple Android devices are connected, a manual specification of the device is required during initialization. Otherwise, the system will not be able to identify which one needs to be controlled. Use [airtest.core.api.connect_device](https://airtest.readthedocs.io/en/latest/all_module/airtest.core.api.html#airtest.core.api.connect_device) Connect the specified device, as shown in the before. Connecting the specified device with `connect_device` will return a `Device` object. Pass this object to `AndroidUiautomationPoco` as the first parameter to initialize `poco`. Then use this `poco` instance to get the UI of the specified device and operate on it. ```python from airtest.core.api import connect_device from poco.drivers.android.uiautomation import AndroidUiautomationPoco dev = connect_device('Android://:/') poco = AndroidUiautomationPoco(dev) # ... ``` ### Requirements **Android SDK API version >= 19**, ie Android 4.4 and above, the higher the version compatibility, the better. Poco does not need to be configured with any dependencies on Android native apps, as long as the phone is in usb debug mode (some phones need to be opened with usb installation, usb emulation click, etc., all in the developer options). Initializing poco. For example, PocoService.apk will be installed automatically to the phone. If the installation prompt pops up, click Agree, otherwise poco will not be available. A total of two apps will be installed during this process. If the PocoService has been already loaded and the "poco service is running!" message is displayed, but it can't run, try to open additional phone permissions and see if there are any other settings in the phone that might be preventing the correct functioning. ## API guidelines * Equipment operation:[airtest core API](https://airtest.readthedocs.io/en/latest/all_module/airtest.core.api.html) * Image recognition: [airtest doc](https://airtest.readthedocs.io/en/latest/index.html) * UI selection and operation::[poco doc](http://poco.readthedocs.io)