II. How to Use Poco API Documentation¶

1.Preface¶

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 poco.drivers.android.uiautomation import AndroidUiautomationPoco
  poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
  

# Click on the center of the screen

poco.click([0.5,0.5])


# Long click on the center of the screen

poco.long_click([0.5,0.5])


# Swipe left

poco.swipe([0.9,0.5],[0.3,0.5])


# 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 poco.click([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.

../_images/hunter-poco-coordinate-system.png

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 poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)

poco("com.mumu.launcher:id/workspace").child("android.view.ViewGroup")

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 poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)

# Click on a control

poco(text="NetEase").click()


# Get the value of the name attribute of a control

poco(text="NetEase").attr("name")


# Determine if the control exists

poco(text="NetEase").exists()


# Set the text information of the control

poco("android.widget.EditText").set_text("123")


# ...

③ 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

poco("star_single").focus([0,0]).click()


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

poco("star_single").focus([0.5,0.5]).click()


# Click on the outside area of the star control

poco("star_single").focus([-0.5,0.5]).click()

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 poco.drivers.android.uiautomation 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.