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.
3.Poco APIs and Related Exceptions¶
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:
- Long click:
- Custom rendering 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
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.
① APIs related to control location¶
The Poco control provides us with various methods of locating by using the hierarchical UI tree:
- Child node:
- All child nodes:
- Offspring node:
- Parent node:
- Sibling node:
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.
② APIs related to control operation¶
There are many APIs for operating controls:
- Get the attribute information of a control:
- Click on a control:
- Drag a control:
- A control exist:
- Internal or external offset of a control:
- Get the text property value of a control:
- Set the text property value of a control:
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 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.