.. image:: doc/img/logo-no-padding.png

Poco ポコ

|docs| |chat on slack|

A cross-engine UI automation framework. Unity3D/cocos2dx-*/Android native APP/iOS native APP/(Other engines SDK)/...

Example

First you should connect your Android phone, for example, via usb cable and enable the ADB DEBUG MODE.

.. image:: doc/img/overview.gif

.. code-block:: python

# coding=utf-8

import time
from poco.drivers.unity3d import UnityPoco

poco = UnityPoco()

poco('btn_start').click()
time.sleep(1.5)

shell = poco('shell').focus('center')
for star in poco('star'):
    star.drag_to(shell)
time.sleep(1)

assert poco('scoreVal').get_text() == "100", "score correct."
poco('btn_back', type='Button').click()

More examples_ here.

Tools for writing test scripts

To retrieve the UI hierarchy of the game, please use our AirtestIDE_ (an IDE for writing test scripts) or standalone PocoHierarchyViewer_ (to view the hierarchy and attributes only but lightweight) !

.. image:: doc/img/hunter-inspector.png

Installation

In order to use Poco, you must install Poco python library on your host and also install the poco-sdk_ in your game/app.

Poco can be installed straightforward with pip command. It is called pocoui.

.. code-block:: bash

pip install pocoui

SDK Integration

For poco-sdk integration please refer to Integration Guide_

Features

• supports mainstream game engines, including: Unity3D, cocos2dx-js, cocos2dx-lua, Android/iOS native apps
• retrieves UI Elements Hierarchy in game's runtime
• is super fast and impact-free to the game
• allows straightforward SDK integration to the game (within in 5 minutes)
• provides powerful APIs that are engine independent
• supports multi-touch e.g. fling/pinch/... (and more is coming soon)
• support gps, accelerometer and gyro sensors, rotation (landscape/portrait) and other sensors as input (coming soon)
• is extensible to other private engines by implementing poco-sdk_ .
• is compatible with Python 2.7 and Python 3.3-3.6.

Documentation

Online docs_.

Use poco on platforms/engines

This section guide you how to start to use poco to write your test cases on different platforms/engines.

Poco drivers_

Tutorials and examples

This section will let your know all basic features of poco.

• basic usage_
• interact with Buttons and Labels_
• drag and swipe operations_
• advanced selections_
• play with coordinate system and local positioning_
• iteration over elements_
• handling exceptions_
• waiting for events_
• play with unittest framework_
• optimize speed by freezing UI_

.. _basic usage: http://poco.readthedocs.io/en/latest/source/doc/poco-example/basic.html .. _interact with Buttons and Labels: http://poco.readthedocs.io/en/latest/source/doc/poco-example/interact_with_buttons_and_labels.html .. _drag and swipe operations: http://poco.readthedocs.io/en/latest/source/doc/poco-example/drag_and_swipe_operations.html .. _advanced selections: http://poco.readthedocs.io/en/latest/source/doc/poco-example/advanced_selections.html .. _play with coordinate system and local positioning: http://poco.readthedocs.io/en/latest/source/doc/poco-example/play_with_coordinate_system_and_local_positioning.html .. _iteration over elements: http://poco.readthedocs.io/en/latest/source/doc/poco-example/iteration_over_elements.html .. _handling exceptions: http://poco.readthedocs.io/en/latest/source/doc/poco-example/handling_exceptions.html .. _waiting for events: http://poco.readthedocs.io/en/latest/source/doc/poco-example/waiting_events.html .. _play with unittest framework: http://poco.readthedocs.io/en/latest/source/doc/poco-example/play_with_unittest_framework.html .. _optimize speed by freezing UI: http://poco.readthedocs.io/en/latest/source/doc/poco-example/optimize_speed_by_freezing_UI.html

How to use Poco

Poco supports different types of engines by different drivers. For different engines please initialize poco instance by corresponding driver. Remember to connect an Android device to your PC/mac with a running game or launch and keep the game/app active on PC/mac.

Following example shows how to initialize poco instance for

• Unity3D.

.. code-block:: python

from poco.drivers.unity3d import UnityPoco

poco = UnityPoco()
# for unity editor on windows
# poco = UnityPoco(('localhost', 5001), unity_editor=True)

ui = poco('...')
ui.click()

• Android native APP

.. code-block:: python

from poco.drivers.android.uiautomation import AndroidUiautomationPoco

poco = AndroidUiautomationPoco()
poco.device.wake()
poco(text='Clock').click()

• for other engines, refer to Poco drivers_ for more details. If poco drivers does not support your engine, please refer to Integration Guide_.

Working with Poco Objects

Basic Selector """"""""""""""

UI element objects can be selected by invoking poco(...) function instance. The function traverses through the render tree structure and selects all the corresponding UI elements matching the query expression.

The function takes one mandatory argument node name, the optional arguments can be substituted too and they refer to specific node properties. For more information, refer to API Reference selecting UI_.

.. code-block:: python

# select by node name
poco('bg_mission')

# select by name and other properties
poco('bg_mission', type='Button')
poco(textMatches='^据点.*$', type='Button', enable=True)

.. image:: doc/img/hunter-poco-select-simple.png

Relative Selector """""""""""""""""

When there is any ambiguity in the selected objects by node names/node types or object unable to select, the relative selector tries to select the element object by hierarchy in following manner

.. code-block:: python

# select by direct child/offspring
poco('main_node').child('list_item').offspring('item')

.. image:: doc/img/hunter-poco-select-relative.png

Sequence Selector """""""""""""""""

Tree indexing and traversing is performed by default from up to down or from left to right. In case that the 'not-yet-traversed' nodes are removed from the screen, the exception is raised. The exception is not raised in case when the 'already-traversed' nodes are removed and in this case the traversing continues in previous order despite the fact that the nodes in views were rearranged during the travers process.

.. code-block:: python

items = poco('main_node').child('list_item').offspring('item')
print(items[0].child('material_name').get_text())
print(items[1].child('material_name').get_text())

.. image:: doc/img/hunter-poco-select-sequence.png

Iterate over a collection of objects """"""""""""""""""""""""""""""""""""

Following code snippet shows how to iterate over the collection of UI objects

.. code-block:: python

# traverse through every item
items = poco('main_node').child('list_item').offspring('item')
for item in items:
    item.child('icn_item')

.. image:: doc/img/hunter-poco-iteration.png

Get object properties """""""""""""""""""""

Following examples shows how to obtain various properties of an object

.. code-block:: python

mission_btn = poco('bg_mission')
print(mission_btn.attr('type'))  # 'Button'
print(mission_btn.get_text())  # '据点支援'
print(mission_btn.attr('text'))  # '据点支援' equivalent to .get_text()
print(mission_btn.exists())  # True/False, exists in the screen or not

Object Proxy Related Operation """"""""""""""""""""""""""""""

This section describes object proxy related operations

click '''''

The anchorPoint of UI element is attached to the click point by default. When the first argument (the relative click position) is passed to the function, the coordinates of the top-left corner of the bounding box become [0, 0] and the bottom right corner coordinates are [1, 1]. The click range area can be less than 0 or larger than 1. If the click range area lies in the interval (0, 1), it means it is beyond the bounding box.

Following example demonstrates how to use click function

.. code-block:: python

poco('bg_mission').click()
poco('bg_mission').click('center')
poco('bg_mission').click([0.5, 0.5])    # equivalent to center
poco('bg_mission').focus([0.5, 0.5]).click()  # equivalent to above expression

.. image:: doc/img/hunter-poco-click.png

swipe '''''

The anchorPoint of UI element is taken as the origin, the swipe action is performed towards the given direction with the certain distance.

Following example shows how to use the swipe function

.. code-block:: python

joystick = poco('movetouch_panel').child('point_img')
joystick.swipe('up')
joystick.swipe([0.2, -0.2])  # swipe sqrt(0.08) unit distance at 45 degree angle up-and-right
joystick.swipe([0.2, -0.2], duration=0.5)

.. image:: doc/img/hunter-poco-swipe.png

drag ''''

Drag from current UI element to the target UI element.

Following example shows how to use the drag_to function

.. code-block:: python

poco(text='突破芯片').drag_to(poco(text='岩石司康饼'))

.. image:: doc/img/hunter-poco-drag.png

focus (local positioning) '''''''''''''''''''''''''

The anchorPoint is set as the origin when conducting operations related to the node coordinates. If the the local click area is need, the focus function can be used. The coordinate system is similar to the screen coordinates - the origin is put to the top left corner of the bounding box and with length of unit of 1, i.e the coordinates of the center are then [0.5, 0.5] and the bottom right corner has coordinates [1, 1].

.. code-block:: python

poco('bg_mission').focus('center').click()  # click the center

The focus function ca