poco.proxy module

class UIObjectProxy(poco, name=None, **attrs)[source]

Bases: 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.

Parameters:
  • 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)[source]

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.

Warning

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

Parameters:item (int) – the index.
Returns:a new UI proxy object representing the n-th of the current UI elements.
Return type:UIObjectProxy
__iter__()[source]

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.

Yields:UIObjectProxy – a generator yielding new UI proxy represents the specific UI element iterated over
Raises:PocoTargetRemovedException – when hierarchy structure has changed and it is attempted to access to the nonexistent UI element over the iteration
__len__()[source]

Return the number of selected UI elements.

Returns:returns 0 if none of the UI element matches the query expression otherwise returns the number of selected UI elements
Return type:int
attr(*args, **kwargs)[source]

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.

Parameters: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
Returns: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.
Raises:PocoNoSuchNodeException – when the UI element does not exists

Note

Exception NodeHasBeenRemovedException is caught automatically.

child(name=None, **attrs)[source]

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

Parameters:
  • 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
Returns:

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

Return type:

UIObjectProxy

children()[source]

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

Returns:a new UI proxy object
Return type:UIObjectProxy
click(*args, **kwargs)[source]

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.

Parameters:
  • 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.
Raises:

PocoNoSuchNodeException – raised when the UI element does not exist

double_click(*args, **kwargs)[source]

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.

Parameters:
  • 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.
Raises:

PocoNoSuchNodeException – raised when the UI element does not exist

drag_to(target, duration=2.0)[source]

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

Parameters:
  • 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
Raises:

PocoNoSuchNodeException – raised when the UI element does not exist

exists(*args, **kwargs)[source]

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

Returns:True if exists otherwise False
Return type:bool
focus(f)[source]

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

Parameters: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’.
Returns:a new UI proxy object (copy)
Return type:UIObjectProxy
get_bounds(*args, **kwargs)[source]

Get the parameters of bounding box of the UI element.

Returns:4-list (top, right, bottom, left) coordinates related to the edge of screen in NormalizedCoordinate system
Return type:list <float>
get_name()[source]

Get the UI element name attribute

Returns:UI element name attribute
Return type:str
get_position(*args, **kwargs)[source]

Get the position of the UI elements.

Parameters:focus – focus point of UI proxy, see .focus() for more details
Returns:coordinates (x, y) in NormalizedCoordinate system
Return type:2-list/2-tuple
Raises:TypeError – raised when unsupported focus type is specified
get_size(*args, **kwargs)[source]

Get the UI element size in NormalizedCoordinate system.

Returns:size [width, height] in range of 0 ~ 1.
Return type:2-list
get_text()[source]

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

Returns: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.
Return type:str
invalidate()[source]

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

alias is refresh()

Example

>>> a = poco(text="settings")
>>> print(a.exists())
>>> a.refresh()
>>> print(a.exists())
long_click(*args, **kwargs)[source]

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.

Parameters:duration (float) – whole action duration.
Returns:the same as poco.pocofw.Poco.long_click(), depending on poco agent implementation.
nodes

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

offspring(name=None, **attrs)[source]

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.

Parameters:
  • 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
Returns:

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

Return type:

UIObjectProxy

parent()[source]

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

Warning

Experimental method, may not be available for all drivers.

Returns:a new UI proxy object representing the direct parent of the first UI element.
Return type:UIObjectProxy
pinch(direction=u'in', percent=0.6, duration=2.0, dead_zone=0.1)[source]

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

Parameters:
  • 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
Raises:

PocoNoSuchNodeException – raised when the UI element does not exist

rclick(*args, **kwargs)[source]

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.

Parameters:
  • 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.
Raises:

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()

Example

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

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.

Parameters:
  • 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
Raises:

PocoNoSuchNodeException – raised when the UI element does not exist

set_text(text)[source]

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

Parameters:text – the text value to be set
Raises:InvalidOperationException – when unable to mutate text value of the UI element
setattr(*args, **kwargs)[source]

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.

Parameters:
  • name – attribute name
  • val – new attribute value to cast
Raises:

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

sibling(name=None, **attrs)[source]

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

Parameters:
  • 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
Returns:

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

Return type:

UIObjectProxy

start_gesture()[source]

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.

Examples

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()

Note

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

Returns:an object for building serialized gesture action.
Return type:PendingGestureAction
swipe(*args, **kwargs)[source]

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

Parameters:
  • 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
Raises:

PocoNoSuchNodeException – raised when the UI element does not exist

wait(timeout=3)[source]

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

Parameters:timeout – maximum waiting time in seconds
Returns:self
Return type:UIObjectProxy
wait_for_appearance(timeout=120)[source]

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

Parameters:timeout – maximum waiting time in seconds
Raises:PocoTargetTimeout – when timeout
wait_for_disappearance(timeout=120)[source]

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

Parameters:timeout – maximum waiting time in seconds
Raises:PocoTargetTimeout – when timeout