poco.proxy module

class UIObjectProxy(poco, name=None, **attrs)[源代码]

基类:object

UI Proxy class that represents the UI element on target device.

Any action performing on this instance is handled by Poco. It is not necessary to initialize this object manually. See QueryCondition for more details about how to select the UI elements.

参数:
  • poco – the poco instance

  • name – query condition of “name” attribute, i.e. the UI element(s) with name name will be selected

  • attrs – other query expressions except for the name

__getitem__(item)[源代码]

Select the specific UI element by index. If this UI proxy represents a set of UI elements, then use this method to access the specific UI element. The new UI element will be wrapped by UIObjectProxy instance and therefore the returned value is also the UI proxy object.

The order of UI elements are determined by their position on the screen and not by the selection sequence. This rule is called “L2R U2D” (one by one from left to right, line by line from up to down), i.e. the most top left UI element is always the first one. See IterationOverUI for more details.

警告

This method may cause some performance issues depending on implementation of PocoAgent.

参数:

item (int) – the index.

返回:

a new UI proxy object representing the n-th of the current UI elements.

返回类型:

UIObjectProxy

__iter__()[源代码]

Similar method to .__getitem__() with the difference that this method iterates over all UI elements. The order rules of UI elements is same as for .__getitem__(). See IterationOverUI for more details.

生成器:

UIObjectProxy – a generator yielding new UI proxy represents the specific UI element iterated over

抛出:

PocoTargetRemovedException – when hierarchy structure has changed and it is attempted to access to the nonexistent UI element over the iteration

__len__()[源代码]

Return the number of selected UI elements.

返回:

returns 0 if none of the UI element matches the query expression otherwise returns the number of selected UI elements

返回类型:

int

attr(name)[源代码]

Retrieve the attribute of UI element by given attribute name. Return None if attribute does not exist. If attribute type is str, it is encoded to utf-8 as str in Python2.7.

参数:

name

attribute name, it can be one of the following or any other customized type implemented by SDK

  • visible: whether or not it is visible to user

  • text: string value of the UI element

  • type: the type name of UI element from remote runtime

  • pos: the position of the UI element

  • size: the percentage size [width, height] in range of 0~1 according to the screen

  • name: the name of UI element

  • …: other sdk implemented attributes

返回:

None if no such attribute or its value is None/null/nil/etc. Otherwise the attribute value is returned. The returned value type is json serializable. In both py2 and py3, if the attribute value in remote is a text-like object, the return value type will be str.

抛出:

PocoNoSuchNodeException – when the UI element does not exists

备注

Exception NodeHasBeenRemovedException is caught automatically.

child(name=None, **attrs)[源代码]

Select the direct child(ren) from the UI element(s) given by the query expression, see QueryCondition for more details about the selectors.

参数:
  • name – query expression of attribute “name”, i.e. the UI elements with name name will be selected

  • attrs – other query expression except for the name

返回:

a new UI proxy object representing the child(ren) of current UI element(s)

返回类型:

UIObjectProxy

children()[源代码]

The same as .child() but it selects all children from the UI element(s).

返回:

a new UI proxy object

返回类型:

UIObjectProxy

click(focus=None, sleep_interval=None)[源代码]

Perform the click action on the UI element(s) represented by the UI proxy. If this UI proxy represents a set of UI elements, the first one in the set is clicked and the anchor point of the UI element is used as the default one. It is also possible to click another point offset by providing focus argument.

See CoordinateSystem for more details.

参数:
  • focus (2-tuple/2-list/str) – an offset point (x, y) from the top left corner of the UI element(s), values must be in range of 0~1. This argument can be also specified by ‘anchor’ or ‘center’. ‘Center’ means to click the center of bounding box of UI element.

  • sleep_interval – number of seconds to wait after this action. Default is None which is the default sleep interval. This value can be configured by Poco initialization. See configuration at poco initialization for more details.

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

double_click(focus=None, sleep_interval=None)[源代码]

Perform the double click action on the UI element(s) represented by the UI proxy. If this UI proxy represents a set of UI elements, the first one in the set is clicked and the anchor point of the UI element is used as the default one. It is also possible to click another point offset by providing focus argument.

See CoordinateSystem for more details.

参数:
  • focus (2-tuple/2-list/str) – an offset point (x, y) from the top left corner of the UI element(s), values must be in range of 0~1. This argument can be also specified by ‘anchor’ or ‘center’. ‘Center’ means to double click the center of bounding box of UI element.

  • sleep_interval – number of seconds to wait after this action. Default is None which is the default sleep interval. This value can be configured by Poco initialization. See configuration at poco initialization for more details.

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

drag_to(target, duration=2.0)[源代码]

Similar to swipe action, but the end point is provide by a UI proxy or by fixed coordinates.

参数:
  • target (UIObjectProxy) – a UI proxy or 2-list/2-tuple coordinates (x, y) in NormalizedCoordinate system

  • duration (float) – time interval in which the action is performed

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

exists()[源代码]

Test whether the UI element is in the hierarchy. Similar to .attr('visible').

返回:

True if exists otherwise False

返回类型:

bool

focus(f)[源代码]

Get a new UI proxy copy with the given focus. Return a new UI proxy object as the UI proxy is immutable.

参数:

f (2-tuple/2-list/str) – the focus point, it can be specified as 2-list/2-tuple coordinates (x, y) in NormalizedCoordinate system or as ‘center’ or ‘anchor’.

返回:

a new UI proxy object (copy)

返回类型:

UIObjectProxy

get_bounds()[源代码]

Get the parameters of bounding box of the UI element.

返回:

4-list (top, right, bottom, left) coordinates related to the edge of screen in NormalizedCoordinate system

返回类型:

list <float>

get_name()[源代码]

Get the UI element name attribute

返回:

UI element name attribute

返回类型:

str

get_position(focus=None)[源代码]

Get the position of the UI elements.

参数:

focus – focus point of UI proxy, see .focus() for more details

返回:

coordinates (x, y) in NormalizedCoordinate system

返回类型:

2-list/2-tuple

抛出:

TypeError – raised when unsupported focus type is specified

get_size()[源代码]

Get the UI element size in NormalizedCoordinate system.

返回:

size [width, height] in range of 0 ~ 1.

返回类型:

2-list

get_text()[源代码]

Get the text attribute of the UI element. Return None if no such attribute. Similar to .attr('text').

返回:

None if the UI element does not have the text element, otherwise the utf-8 encoded text value. In both py2 and py3, the return value type will be str.

返回类型:

str

invalidate()[源代码]

Clear the flag to indicate to re-query or re-select the UI element(s) from hierarchy.

alias is refresh()

示例

>>> a = poco(text="settings")
>>> print(a.exists())
>>> a.refresh()
>>> print(a.exists())
long_click(duration=2.0)[源代码]

Perform the long click action on the UI element(s) represented by the UI proxy. If this UI proxy represents a set of UI elements, the first one in the set is clicked and the anchor point of the UI element is used as the default one. Similar to click but press the screen for the given time interval and then release.

参数:

duration (float) – whole action duration.

返回:

the same as poco.pocofw.Poco.long_click(), depending on poco agent implementation.

property nodes

Readonly property accessing the UI element(s) in the remote runtime.

offspring(name=None, **attrs)[源代码]

Select the offsprings including the direct child(ren) from the UI element(s) given by the query expression, see QueryCondition for more details about selectors.

参数:
  • name – query expression of attribute “name”, i.e. the UI elements with name name will be selected

  • attrs – other query expression except for the name

返回:

a new UI proxy object representing the child(ren) of current UI element(s)

返回类型:

UIObjectProxy

parent()[源代码]

Select the direct parent from the UI element(s) given by the query expression, see QueryCondition for more details about the selectors.

警告

Experimental method, may not be available for all drivers.

返回:

a new UI proxy object representing the direct parent of the first UI element.

返回类型:

UIObjectProxy

pinch(direction='in', percent=0.6, duration=2.0, dead_zone=0.1)[源代码]

Squeezing or expanding 2 fingers on this UI with given motion range and duration.

参数:
  • direction (str) – pinching direction, only “in” or “out”. “in” for squeezing, “out” for expanding

  • percent (float) – squeezing range from or expanding range to of the bounds of the UI

  • duration (float) – time interval in which the action is performed

  • dead_zone (float) – pinching inner circle radius. should not be greater than percent

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

rclick(focus=None, sleep_interval=None)[源代码]

Perform the right click action on the UI element(s) represented by the UI proxy. If this UI proxy represents a set of UI elements, the first one in the set is clicked and the anchor point of the UI element is used as the default one. It is also possible to click another point offset by providing focus argument.

See CoordinateSystem for more details.

参数:
  • focus (2-tuple/2-list/str) – an offset point (x, y) from the top left corner of the UI element(s), values must be in range of 0~1. This argument can be also specified by ‘anchor’ or ‘center’. ‘Center’ means to click the center of bounding box of UI element.

  • sleep_interval – number of seconds to wait after this action. Default is None which is the default sleep interval. This value can be configured by Poco initialization. See configuration at poco initialization for more details.

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

refresh()

Clear the flag to indicate to re-query or re-select the UI element(s) from hierarchy.

alias is refresh()

示例

>>> a = poco(text="settings")
>>> print(a.exists())
>>> a.refresh()
>>> print(a.exists())
scroll(direction='vertical', percent=0.6, duration=2.0)[源代码]

Simply touch down from point A and move to point B then release up finally. This action is performed within specific motion range and duration.

参数:
  • direction (str) – scrolling direction. “vertical” or “horizontal”

  • percent (float) – scrolling distance percentage of selected UI height or width according to direction

  • duration (float) – time interval in which the action is performed

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

set_text(text)[源代码]

Set the text attribute of the UI element. If the UI element does not support mutation, an exception is raised

参数:

text – the text value to be set

抛出:

InvalidOperationException – when unable to mutate text value of the UI element

setattr(name, val)[源代码]

Change the attribute value of the UI element. Not all attributes can be casted to text. If changing the immutable attributes or attributes which do not exist, the InvalidOperationException exception is raised.

参数:
  • name – attribute name

  • val – new attribute value to cast

抛出:

InvalidOperationException – when it fails to set the attribute on UI element

sibling(name=None, **attrs)[源代码]

Select the sibling(s) from the UI element(s) given by the query expression, see QueryCondition for more details about the selectors.

参数:
  • name – query expression of attribute “name”, i.e. the UI elements with name name will be selected

  • attrs – other query expression except for the name

返回:

a new UI proxy object representing the child(ren) of current UI element(s)

返回类型:

UIObjectProxy

start_gesture()[源代码]

Start a gesture action. This method will return a PendingGestureAction object which is able to generate decomposed gesture steps. You can invoke .to and .hold any times in a chain. See the following example.

示例

poco = Poco(...)
ui1 = poco('xxx')
ui2 = poco('yyy')

# touch down on ui1 and hold for 1s
# then drag to ui2 and hold for 1s
# finally release(touch up)
ui1.start_gesture().hold(1).to(ui2).hold(1).up()

备注

always starts touching down at the position of current UI object.

返回:

an object for building serialized gesture action.

返回类型:

PendingGestureAction

swipe(direction, focus=None, duration=0.5)[源代码]

Perform a swipe action given by the direction from this UI element. For notices and limitations see .click().

参数:
  • direction (2-tuple/2-list/str) – coordinates (x, y) in NormalizedCoordinate system, it can be also specified as ‘up’, ‘down’, ‘left’, ‘right’. Swipe ‘up’ is equivalent to [0, -0.1], swipe ‘down’ is equivalent to [0, 0.1], swipe ‘left’ is equivalent to [-0.1, 0] and swipe ‘right’ is equivalent to [0.1, 0]

  • focus (2-tuple/2-list/str) – see .click() for more details

  • duration (float) – time interval in which the action is performed

抛出:

PocoNoSuchNodeException – raised when the UI element does not exist

wait(timeout=3)[源代码]

Block and wait for max given time before the UI element appears.

参数:

timeout – maximum waiting time in seconds

返回:

self

返回类型:

UIObjectProxy

wait_for_appearance(timeout=120)[源代码]

Block and wait until the UI element appears within the given timeout. When timeout, the PocoTargetTimeout is raised.

参数:

timeout – maximum waiting time in seconds

抛出:

PocoTargetTimeout – when timeout

wait_for_disappearance(timeout=120)[源代码]

Block and wait until the UI element disappears within the given timeout.

参数:

timeout – maximum waiting time in seconds

抛出:

PocoTargetTimeout – when timeout