Skip to content

二、如何使用Poco API文档

1. 前言

除了使用AirtestIDE帮助我们录制Poco脚本之外,我们还可以借助Poco API文档,查找和学习更多与Poco框架相关的内容,帮助我们写出内容更加丰富Poco脚本。

我们在poco的API文档中,不仅仅可以搜索框架的API及其用法,还可以查看poco的一些入门教程和poco-SDK的接入教程:

image-20211122114201550

2. Poco入门教程

在Poco的入门教程中,汇总了框架的绝大部分内容,包含poco脚本的示例、poco框架的安装、入门教学用例poco如何定位控件poco的核心API介绍poco使用的坐标系等等:

image-20211122114713733

3. Poco框架的API及相关异常

1)Poco类的方法

我们可以在这里找到Poco类的所有方法和参数:

image-20211122143410833

① 常用API介绍

在Poco类里,我们常用的API,比如:

  • 点击:click
  • 冻结:freeze
  • 长按:long_click
  • 滑动:swipe
  • 自定义渲染分辨率:use_render_resolution
  • ......
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)

# 单击画面中心位置
poco.click([0.5,0.5])

# 长按画面中心位置
poco.long_click([0.5,0.5])

# 向左滑动
poco.swipe([0.9,0.5],[0.3,0.5])

# 冻结当前的UI树,可提高poco查找效率
frozen_poco = poco.freeze()

# 自定义渲染分辨率,为更好支持更多不兼容的全面屏设备
poco.use_render_resolution(True, (0 ,100 ,1080 ,2020))
② Poco使用的坐标系

Poco的坐标系与Airtest不一样,Airtest使用的是绝对坐标系,在Airtest的脚本里,我们可以传入类似 touch([500,500]) 这样的绝对坐标;但Poco只能接受绝对坐标(归一化坐标系),如上述示例中的 poco.click([0.5,0.5])

归一化坐标系就是将屏幕宽和高按照单位一来算,这样UI在poco中的宽和高其实就是相对于屏幕的百分比大小了,好处就是不同分辨率设备之间,同一个UI的归一化坐标系下的位置和尺寸是一样的,有助于编写跨设备测试用例。

归一化坐标系的空间是均匀的,屏幕正中央一定是(0.5, 0.5),其他标量和向量的计算方法同欧式空间。

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

2)Poco控件类的方法

Poco控件类的所有方法和参数我们可以在这里找到:

image-20211122151234064

在Poco框架中,最重要的就是学会如何定位控件以及对控件进行各种操作。

① 控件定位相关的API

Poco控件给我们提供了利用树的层级关系来定位的各种方法:

  • 子节点:child
  • 所有子节点:children
  • 子孙节点:offspring
  • 父节点:parent
  • 兄弟节点: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")

我们需要根据控件树的详细层级关系,来选去合适的定位方法来定位我们的Poco控件。

② 控件操作相关的API

控件操作的API就非常多了:

  • 获取控件的属性信息:attr
  • 点击:click
  • 拖动:drag_to
  • 存在:exists
  • 内外偏移:focus
  • 获取控件的text属性值:get_text
  • 设置控件的text属性值:set_text
  • ......
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)

# 控件点击操作
poco(text="网易大神").click()

# 获取控件的name属性值
poco(text="网易大神").attr("name")

# 判断控件存在
poco(text="网易大神").exists()

# 设置控件的文本信息
poco("android.widget.EditText").set_text("123")

# ......
③ 控件使用的坐标系

局部坐标系是为了表示相对于某UI的坐标。局部坐标系以UI包围盒左上角为原点,向右为x轴,向下为y轴,包围盒宽和高均为单位1。其余的定义和归一化坐标系类似。

局部坐标系可以更灵活地定位UI内或外的位置,例如(0.5, 0.5)就代表UI的正中央,超过1或小于0的坐标值则表示UI的外面。内外部偏移方法focus就是依据这个坐标系原理实现的。

image-20211122153605228

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

# 点击星星控件左上角的位置
poco("star_single").focus([0,0]).click()

# 点击星星控件的中心位置,等同于poco("star_single").click()
poco("star_single").focus([0.5,0.5]).click()

# 点击星星控件的外部位置
poco("star_single").focus([-0.5,0.5]).click()

3)Poco的异常模块

在这里我们可以看到Poco相关的一些异常模块:

image-20211122154401333

我们在编写脚本的过程中,最常遇到的报错应该是 PocoNoSuchNodeExceptionPocoTargetTimeout了。

PocoNoSuchNodeException 是找不到控件的报错,大概有以下几种情况:

  • 控件不存在于当前页面内
  • 控件定位脚本编写错误,无法定位到目标控件

PocoTargetTimeout常见于使用wait等待控件出现,一直没等到而出现的超时报错。

4. 不同平台如何实例化Poco对象

我们可以在这里找到绝大部分平台,实例化Poco对象的示例:

image-20211122160404186

# unity项目的poco初始化

# import unity poco driver from this path
from poco.drivers.unity3d import UnityPoco

# then initialize the poco instance in the following way
poco = UnityPoco()
# android项目的poco初始化

from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco()

更重要的是,这里还给出了多设备初始化Poco的案例,同学们可以详细查看下:

image-20211122164141070

5. 在不同平台嵌入Poco-SDK

在Poco API文档的这部分内容,给我们提供了各种游戏引擎接入Poco-SDK的详细教程,同学们可以在这里找到对应引擎的接入教程,来使用我们的Poco框架:

image-20211122164455371