Skip to content

II. How to Use Poco API Documentation


In addition to using AirtestIDE to record Poco scripts, we can also use the Poco API documentation to search and learn more about the Poco framework to write more comprehensive Poco scripts. In Poco's API documentation, we can not only search for the framework's APIs and their usage, but also view some introductory tutorials for Poco and for integrating Poco-SDK:


2.Poco Tutorial for Beginners

This module covers the major content of the framework, including examples of Poco scripts, installation of the Poco framework, use case tutorials, how to locate controls in Poco, an introduction to Poco's core APIs, and the coordinate system used by Poco.


1) Methods of the Poco class

We can find all methods and parameters of the Poco classes here:


① Introduction to commonly used APIs

In the Poco class, the APIs commonly use include:

  • Click: click
  • Freeze: freeze
  • Long click: long_click
  • Swipe: swipe
  • Custom rendering resolution: use_render_resolution
  • ...
- from import AndroidUiautomationPoco
  poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)

# Click on the center of the screen[0.5,0.5])

# Long click on the center of the screen


# Swipe left


# Freeze the current UI element tree to improve Poco's search efficiency.

frozen_poco = poco.freeze()

# Customize rendering resolution to better support more incompatible full-screen devices.

poco.use_render_resolution(True, (0 ,100 ,1080 ,2020))
② Coordinate system used by Poco

Poco's coordinate system is different from Airtest's. Airtest uses an absolute coordinate system, where we can input absolute coordinates in the script, such as touch([500,500]). However, Poco only accepts absolute coordinates in a normalized coordinate system, as shown in the above example[0.5,0.5]).

The normalized coordinate system means calculating the screen width and height in the range 0 to 1. This means that the width and height of UI in Poco are actually relative percentage sizes to the screen. The benefit is that, in the normalized coordinate system, the position and size of the same UI are the same across different devices with different resolutions. This helps in writing cross-device test cases.

The space of the normalized coordinate system is uniform, with the center of the screen always being (0.5, 0.5). The calculation methods for other scalars and vectors are the same as those in Euclidean space.


2) Methods of the Poco control class

We can find all the methods and parameters of the Poco control class here:


In the Poco framework, the most important thing is to learn how to locate controls and perform various operations on them.

The Poco control provides us with various methods of locating by using the hierarchical UI tree:

  • Child node: child
  • All child nodes: children
  • Offspring node: offspring
  • Parent node: parent
  • Sibling node: sibling
from import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)

We need to select the appropriate method for locating the Poco controls based on the detailed hierarchical relationship of the control tree.

There are many APIs for operating controls:

  • Get the attribute information of a control: attr
  • Click on a control:click
  • Drag a control: drag_to
  • A control exist: exists
  • Internal or external offset of a control: focus
  • Get the text property value of a control: get_text
  • Set the text property value of a control: set_text
  • ...
from import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
# Click on a control


# Get the value of the name attribute of a control


# Determine if the control exists


# Set the text information of the control


# ...
③ Coordinate system used by the controls

The local coordinate system is used to represent coordinates relative to a certain UI. The local coordinate system has its origin at the upper-left corner of the UI bounding box, with the x-axis pointing right and the y-axis pointing down. The width and height of the bounding box are both one unit. Other definitions are similar to the normalized coordinate system.

The local coordinate system can locate the position inside or outside of UI in more flexible way. For example, (0.5, 0.5) represents the center of the UI, while coordinate values exceeding 1 or less than 0 indicate the area outside the UI. The focus method for internal and external offset is based on this coordinate system principle.


from poco.drivers.unity3d import UnityPoco
poco = UnityPoco()

# Click on the upper left corner of the star control


# Click on the center of the star control, equivalent to poco("star_single").click()


# Click on the outside area of the star control


3) Poco exceptions

Here we can see some exceptions related to Poco:


During the process of writing scripts, the most common errors are PocoNoSuchNodeException and PocoTargetTimeout.

PocoNoSuchNodeException occurs when the control cannot be found. There are several possible situations: - The control does not exist on the current page. - A mistake is made in the script of control positioning, making it unable to locate the target control.

PocoTargetTimeout is an error occurs due to timeout when using wait API to wait for the appearance of a control.

4.Instantiating Poco Objects on Different Platforms

We can find most of the platforms here where we can instantiate Poco objects.


# Initialization of Poco in Unity project

# Import Unity Poco driver from this path
from poco.drivers.unity3d import UnityPoco

# Then initialize the Poco instance in the following way
poco = UnityPoco()
# Initialization of Poco for Android project

from import AndroidUiautomationPoco
poco = AndroidUiautomationPoco()

More importantly, there are also examples of initializing Poco on multiple devices for your reference.


5.Integrating Poco-SDK in Different Platforms

This section of the Poco API documentation provides tutorials on how to integrate the Poco-SDK into various game engines. You can find the integration tutorials for specific engines here to help you better master the Poco framework.