Skip to content

2.2 Android connection FAQ


If the following content does not solve your problem, please go to the AirtestIDE Issues page and submit the phone model, error log and problem description, we will fix it as soon as possible.

1. Problem self-examination

Turn off the mobile assistant software

Please make sure that there are no other third-party mobile assistants software running in the current environment.If so, please try again after exiting completely. (And you should confirm that no related processes remain in Task Manager, most mobile assistants need to manually terminate the process in Task Manager to exit completely).

Confirm phone settings

Please make sure that the Allow USB debugging option is enabled in the Developer Options section of the phone. Some phones need to select MTP Mode to connect after connecting the USB cable.

If you see the device status in the AirtestIDE device list is unauthorized, as shown in the figure:


Please click on the phone to confirm the Allow USB debugging option, and you can tick to allow this computer to be used for debugging, to avoid repeated operations in the future:


Confirm that ADB is able to connect to the phone normally

If you don't see your device number in the AirtestIDE device list window, please make sure that the phone can connect to ADB normally:

  • Under windows system:

After connecting the phone with the USB cable, open the command line terminal by holding down the shift and right mouse button in this directory--AirtestIDE/airtest/core/android/static/adb/windows, and then type adb.exe devices.

  • Under the mac system:

After unzipping dmg, you will be prompted to install the application to the Application/folder, so you can cd to the Application/ directory on the terminal command line. Next, run ./adb devices.

Example of what should be returned under normal circumstances:

>adb.exe devices
List of devices attached
JTJ4C15A30048654(手机的设备号) device

If the above input does not occur properly, you need to check the following aspects:

  • If you don't see the code device number - device,you need to check if the corresponding official driver software of the phone is installed on your computer.If the driver is not installed, the phone will not be detected.Please check the official website of the corresponding mobile phone brand and download the official driver for installation.
  • It is recommended to use the USB interface on the back of the chassis as much as possible. The USB interface on the front of the main unit may be unstable.
  • You need to turn on the Developer Options on your phone and enable the USB Debuging option.And when accessing the computer, select allow the PC to debug the device, otherwise the phone status is unauthorized and the phone cannot be connected.
  • Be sure to check that all types of the mobile assistants on your computer are turned off and the process has completely exited.(Most mobile assistants need to manually terminate the process in the task manager.)

ADB is the official Android debugging tool provided by Google.Since AirtestIDE and related libraries need to rely on ADB to operate, if you can't see your device through adb devices, you can't continue to use AirtestIDE. Make sure your phone is properly connected to your PC.

### Confirm that the Airtest related files can be installed to the phone normally. If you can see your device in the return result of the adb devices command,but you can't connect to the phone using AirtestIDE, you can continue to check the following aspects:

  • When the device is connected to the IDE for initialization, an application called RotationWatcher.apk will be installed on the phone.(Used to detect if the phone screen is rotating)So there may be a pop-up reminder to install apk on the phone, you need to manually click to agree to install.
  • Some models of mobile phones block ADB's permission to install apk by default.(Especially millet phone)Please open the configuration item in the developer options, otherwise you will not be able to install the necessary apk.
  • If it is a rooted phone, it may be modified because the local folder permissions have been changed causing Airtest does not have permission to put related files into the phone. Please check if the /data/local/tmp folder in the phone has write permission.
  • If the phone has ever installed the STF library, there may be problems such as not being able to click the screen properly.You can try to empty the previously installed STF related files (execute the command adb shell rm /data/local/tmp/mini*), then reconnect the phone to the IDE for initialization.
  • Although some mobile phones can successfully install pocoservices.apk, they may prompt to re-install and fail to start properly during startup.In this case, you need to check whether the network where the mobile phone is located is a special network (for example, open proxy), whether the settings in the developer options of the mobile phone are enabled (related to USB installation and operation related options, some models need to select disable permission monitoring, etc. ).If it is a VIVO/OPPO brand mobile phone, you may need to set the mobile phone default input method to yosemite. Please check the OPPO/VIVO related chapter of this document.

If the mobile phone device number information appears correctly in the window after inputting adb devices, but the mobile phone screen cannot be properly connected and operated in AirtestIDE, please submit issue with the the phone model, error log and problem description.

The following guidelines provide some information that some manufacturers may need to pay attention to. Please check the problem according to your mobile phone model first, and confirm that you can't get it and then submit the issue to github.

Device compatibility

We have already tested the compatibility of the models currently used by most users on the market. Please check the list of confirmed models to confirm that your mobile phone is compatible.(Due to the rapid update of the device, the list has not been maintained for a long time, but most mobile phones on the market are compatible).

If the phone you are using is not on the list, please submit the phone model, error log and problem description to issue.

If the phone you are using shows compatibility in the list, but you are experiencing problems with the actual use, please continue to consult the documentation for troubleshooting.

2. Some manufacturers have special problems with equipment

Here are some settings for some manufacturers' special models. Please check if there is a corresponding option to open according to your mobile phone model.


Please open the "Allow simulated click location", "USB installation", "USB debug (security settings)" options in the "Developer Options".Some options may be required to open Sign in MIUI account (you need to insert SIM card). If these options are not turned on correctly, it may cause the Millet phone to be unable to connect.


MIUI Forum's Instructions on USB Installation and Debugging
If these problems occur, such as clicking on the phone screen and reporting an error, unable to click on the phone screen, etc., please confirm that the Allow simulated click location option in the Millet phone has been turned on.

Some Millet phones complained Failure [INSTALL_FAILED_USER_RESTRICTED: Install canceled by user] when the connection failed,it was because Airtest tried to install apk to the phone but was automatically intercepted by the phone. In addition to the above developer options need to pay attention to open Allow installation of applications through USB, you can also view the phone settings -> authorization management -> USB installation management -> to remove the limitations of the USB installation application.

Some Millet phones can't successfully install the yosemite input method, and the following error is reported when initializing poco:


Cancel the selected state of the Security Keyboard in the language and input method of the system settings:



  1. Display - screen resolution is adjusted to maximum:

As shown in the figure below, some mobile devices (such as some models of Samsung mobile phones) connected to AirtestIDE, the displayed mobile phone screen can not fill the entire screen, please adjust "Screen Resolution" to "WQHD" in the "Settings"-"Display".


  1. In the developer options, turn on unknown sources, cancel permission monitoring.


  1. In the input method settings, cancel the security input
  2. In the developer options, uncheck the ADB installation and open the option to allow debugging only in charging mode.
  3. Permission Monitoring -> Settings -> Automatic Configuration Permissions
  4. For some Huawei models, there may be cases where the click position does not match the actual position (mate20pro, mate7, etc.). You need to set the resolution to the highest in Settings - Display - Screen Resolution.


  1. If the Huawei mobile phone appears to be disconnected automatically within ten seconds after the startup, you can check if the version number of the mobile phone housekeeper is greater than 8.0. If yes, in the mobile phone housekeeper->boot management, find the pocoservice, check the permission from self-start and allow background activities.
    image image


  1. Cancel the safe input, if you encounter Poco initialization failed, the text interface can not be called, you can set the Yosemite input method to the default method in the input method settings:


  1. Some models need to Open security permissions in the developer options, otherwise you may see the following error when initializing poco:



  1. At the bottom of the developer options, check Disable monitoring permissions

  2. Some OPPO models need to enter the password each time the APK is installed: there is no more reliable solution, there is a post for reference Collection:The pits and solutions that can not be automated in each factory phone.

  3. Some OPPO models will fail and report an error when initializing Poco, or when calling the text() interface.The reason may be that the installation or switching of the Yosemite input method failed (you need to enter the OPPO account and password to switch).At this point, you can first set the Yosemite input method to the default input method in the System Settings - Input Method settings.If you have not installed the Yosemite input method, you can find it in the AirtestIDE\airtest\core\android\static\apks directory and manually install it on your phone to start using the Poco function and the text() interface.


Some models of Meizu mobile phones cannot be connected directly through ADB. For details, please refer to this post.


In the developer options, you need to check the Allow imitation location.


3. Full screen problem

IDE Position deviation

There are some apps that don't support full-screen phones. Their images don't fill the entire screen, causing black edges on the screen and poco positioning deviation.The latest version of the IDE has fixed this problem by simply clicking on "Stop" in the Poco Assist window and reconnecting to switch to the current screen rendering resolution.


IDE Custom render resolution

AirtestIDE can adapt to more than 90% of the full screen adaptation problems, for the remaining 10% of the phone, the IDE supports users to set the render resolution by themselves.


Check the render resolution, then enter the render resolution in portrait mode, last click OK.The render resolution is four numbers separated by commas, and the numbers represent offset_x, offset_y, offset_width, offset_heigt in portrait mode.

For example, the resolution of the game big fish came is 1080*2220, and it will have two black edges on the phone. The height of the black edge on the top is 100px, the screen height is 2020px, and the height of the black edge on the bottom is 100px, so the render resolution is (0,100,1080,2020).

Script run offset

When the app does not support the full screen and then the black border appears,the script that runs the poco click will cause a positional offset. Like the image below, poco("PauseButton").click() is executed, but the actual click position is not In line with expectations.


Make sure the current poco or IDE is the latest version, close the virtual keyboard below, and then call poco.use_render_resolution() in the script to switch poco to the current screen render resolution and run the script to achieve accurate Click.


For full screen devices that Airtest cannot support, you can customize the render resolution:

poco.use_render_resolution(True, (0 ,100 ,1080 ,2020))

If the page is switched, switching from a screen that does not support full screen to a screen that supports full screen, that is, a page with black borders -> no black border page, you need to reset the poco resolution, pass "False" using poco.use_render_resolution( False), poco will switch to the full resolution of the phone.

If multiple machines are running and there are common screen mobile phones and full-screen mobile phones, and the app does not support full-screen devices.You need to close the virtual keyboard of all mobile phones,and the script is written in accordance with the script supporting full screen.

4. Other frequently asked questions

Some devices "return" - "home" - "menu" and other buttons are invalid

  • Some devices do not respond correctly to some system button operations, such as HOME, BACK, etc.:

    • vivo Y55A

    • vivo Y67

    • vivo X20 Plus(Screen fingerprint version)

    • Redmi 3X

    • Xiaomi 5C

    For more models, please refer to the Device Compatibility section.

  • Some models are due to system customization reasons. When text is input, the script will exit abnormally:

    • vivo Y55A

    Please make your own catch error in the script, or use poco("xxx").set_text("input") .

Unable to enter password in password box using text() interface

Some models of some manufacturers (such as Huawei, VIVO, etc.) restrict the input of the password box, and must use the system keyboard input when entering the password.This means that when you need to enter a password, if you use Airtest's text() interface directly, you will not be able to type. You need to open the following options to enter the password content normally:


Whether to support the simulator, IOS

Currently the simulator is supported and there are two ways to connect:目前已支持模拟器,目前有两种连接方式:

The iOS connection is also supported, see iOS-Connect.

If the emulator has a black screen during the connection process, check the use javacap option in the connect drop-down menu before connecting the device.Then connect again and you will see the simulator screen normally.

Brush out duplicate equipment

When refreshing, two identical devices were found, with the status of device and offline.

Generally this is because the mobile assistant is turned on, and this situation does not occur when the mobile assistant is turned off and refreshed again.

The emulator-5554 device was brushed when the simulator was not running

The reason:after the emulator opens port 5554, adb will only consider the presence of the device if it detects that the port is open.

Reference link click here

Take the Windows 7 system as an example:

1.Go to the AirtestIDE/airtest/core/android/static/adb/windows folder. Then hold down Shift and right click to enter the command window and type "adb.exe devices".

If the emulator-5554 device appears, go to step 2.

2.Perform the operation:

  a. Execute hotkey Windows + R  
  b. enter "services.msc"  
  c. stop BlueStacks Android Service

Frequent pop-ups where adb.exe has stopped working


Generally, the mobile assistant is forced to occupy the adb. Please turn off the mobile assistant to ensure that the adb.exe process and the mobile assistant process are not in the background, and then try again.

The main reason for this problem is that there may be multiple versions of adb.exe in the local, which will cause conflicts when starting.If airtest is installed in the local Python environment and this error is reported when running the script in AirtestIDE, please refer to ADB Version Conflict.

The phone can be connected, but the device screen is not in the right direction.


Please check the use ADB orientation option first, then click connect to connect the device.


The phone can connect but you can't click on the screen

If the phone can connect to AirtestIDE normally, but the screen is not responding with the mouse, and the program prompts minitouch initialization failed.Please first confirm if there is a Allow simulated click location option in the phone settings and it is active (mainly MIUI phones have this setting).

If the problem persists, you can try disconnecting the phone first, and check Use ADB touch in the drop-down menu of the connect button.


Then click the connect button to connect to the phone, you should be able to use the mouse to operate the screen.

If you use Use ADB touch or Use ADB orientation to successfully connect to the mobile device (this option may need to be checked on some devices that fail to initialize),and when using the command line to run the script you also need to add the corresponding information of these two parameters on the connection string --device Android:/// .For details, please refer to Chapter 4 Running Scripts - Partial Special Parameters of Android Devices.

If you get an error Unable to open device /dev/input/event3 for inspectionopen: Permission denied , you can run the adb shell chmod 777 /dev/input/* command to give the /dev/input directory permission.(This operation may require root access to the phone,and please check the information online to learn how to use the adb shell)

Support issues of other smart device

After connecting to AirtestIDE, there may be a horizontal and vertical display error, or you can't click the screen with the mouse on some smart devices such as TV boxes. You can refer to the above two solutions: check Use ADB touch and the Use ADB orientation option,this may help.If the connection is not successful, you can contact the development team for support.

ADB version conflict in Airtest

In the Windows environment,if there is already adb.exe in the running environment (for example, android_sdk is installed, or other tools have adb.exe), and the ADB version is different from that used in Airtest. An error may occur when running the Airtest script.We will see that the log contains such a statement:

adb server version (40) doesn't match this client (39); killing...
  * daemon started successfully *

This is because the conflict between two different versions of the ADB server running at the same time (in this log, you can see that both the 40 version and the 39 version are used), the solution is to unify all the local adb.exe into the same version.

  • AirtestIDE users:
    • The adb.exe path in the IDE is in AirtestIDE/airtest/core/android/static/adb/windows/adb.exe
    • If you only use the IDE and do not use the local python environment to install airtest, you only need to ensure that the adb.exe used in other local applications and processes is the same version. It is recommended to use the search function of windows to search and replace it all over again.
  • Users using both AirtestIDE and local python:
    • Copy the adb.exe you want to use, and then use it to overwrite adb.exe in the airtest installed in the local python environment(The directory is usually Lib\site-packages\airtest in the python directory).And the path in airtest is airtest/core/android/static/adb/windows/adb.exe.
    • Win7 users should try to use ADB39 version as much as possible. We provide one in the IDE folder, AirtestIDE/tools/adb39/adb.exe, and use it as the benchmark version to cover the adb in other places.
    • Win10 users can directly copy AirtestIDE/airtest/core/android/static/adb/windows/adb.exe in the IDE, this is a 40 version of adb
    • Execute adb.exe version to view the version number.
  • Users who need multi-threaded operation:

If this error occurs frequently after replacing the version, you can try to confirm the folder where adb is located by right-clicking the current adb.exe in the Task Manager and selecting Open File Location.Or consider a full search to confirm that all adb files have been replaced.