poco.pocofw module

class Poco(agent, **options)[source]

Bases: poco.acceleration.PocoAccelerationMixin

Poco standard initializer.

Parameters:
  • agent (PocoAgent) – an agent object for Poco to communicate with the target device. See PocoAgent definition for more details.
  • options
    • action_interval: time interval to wait for the action (such as touch or swipe) completion performed on device and for the UI to become still (stable). Default value is 0.8s.
    • poll_interval: the minimum time needed between each poll events (such as waiting for UI element to appear on the screen). Polling is done periodically.
    • pre_action_wait_for_appearance: time interval to wait before the action (such as click or swipe) is performed. If the target UI element does not appear on the screen after this time interval, the PocoNoSuchNodeException is raised
    • touch_down_duration: Touch down step duration of the click operation last for. If this argument is provided, this value will set to self.agent.input module. Note that not all implementation of poco support this parameter. If not support, you may see a warning.
wait_for_any(objects, timeout=120)[source]

Wait until any of given UI proxies show up before timeout and return the first appeared UI proxy. All UI proxies will be polled periodically. See options poll_interval in Poco’s initialization for more details.

Parameters:
  • objects (Iterable<UIObjectProxy>) – iterable object of the given UI proxies
  • timeout (float) – timeout in seconds, default is 120s
Returns:

the first appeared UI proxy

Return type:

UIObjectProxy

Raises:

PocoTargetTimeout – when none of UI proxies appeared before timeout

wait_for_all(objects, timeout=120)[source]

Wait until all of given UI proxies show up before timeout. All UI proxies will be polled periodically. See option poll_interval in Poco’s initialization for more details.

Parameters:
  • objects (Iterable<UIObjectProxy>) – iterable object of the given UI proxies
  • timeout (float) – timeout in seconds, default is 120s
Raises:

PocoTargetTimeout – when not all of UI proxies appeared before timeout

freeze()[source]

Snapshot current hierarchy and cache it into a new poco instance. This new poco instance is a copy from current poco instance (self). The hierarchy of the new poco instance is fixed and immutable. It will be super fast when calling dump function from frozen poco. See the example below.

Examples

poco = Poco(...)
frozen_poco = poco.freeze()
hierarchy_dict = frozen_poco.agent.hierarchy.dump()  # will return the already cached hierarchy data
Returns:new poco instance copy from current poco instance (self)
Return type:Poco
wait_stable()[source]

Sleep for fixed number of seconds in order to wait for the UI to become still (stable). There is no need to call this method manually. It’s automatically invoked when required.

sleep_for_polling_interval()[source]

Sleep for fixed number of seconds after each poll event. There is no need to call this method manually. It’s automatically invoked when required.

agent

Readonly property to access poco agent instance. See poco.agent.PocoAgent for more details.

Returns:poco agent instance
Return type:poco.agent.PocoAgent
click(pos)[source]

Perform click (touch, tap, etc.) action on target device at given coordinates.

The coordinates (x, y) are either a 2-list or 2-tuple. The coordinates values for x and y must be in the interval between 0 ~ 1 to represent the percentage of the screen. For example, the coordinates [0.5, 0.5] represent the center of the screen and the coordinates [0, 0] represent the top left corner.

See CoordinateSystem for more details about coordinate system.

Examples

Click the point of (100, 100) of screen which resolution is (1920, 1080):

poco.click([100.0 / 1920, 100.0 / 1080])
Parameters:pos (list(float, float) / tuple(float, float)) – coordinates (x, y) in range of 0 to 1
Raises:InvalidOperationException – when clicked outside of the screen
swipe(p1, p2=None, direction=None, duration=2.0)[source]

Perform swipe action on target device from point to point given by start point and end point, or by the direction vector. At least one of the end point or direction must be provided.

The coordinates (x, y) definition for points is the same as for click event. The components of the direction vector (x, y) are also expressed in the range of the screen from 0 to 1.

See CoordinateSystem for more details about coordinate system.

Examples

Following example shows how to perform a swipe action from (100, 100) to (100, 200) on screen with resolution 1920x1080:

poco.swipe([100.0 / 1920, 100.0 / 1080], [100.0 / 1920, 200.0 / 1080])

Or given by the specific direction instead of end point:

poco.swipe([100.0 / 1920, 100.0 / 1080], direction=[0, 100.0 / 1080])
Parameters:
  • p1 (2-list/2-tuple) – start point
  • p2 – end point
  • direction – swipe direction
  • duration (float) – time interval in which the swipe action is performed
Raises:

InvalidOperationException – when the start point of the swipe action lies outside the screen

long_click(pos, duration=2.0)[source]

Similar to click but press the screen for the given time interval and then release

Parameters:
  • pos (2-list/2-tuple) – coordinates (x, y) in range from 0 to 1
  • duration – duration of press the screen
scroll(direction='vertical', percent=0.6, duration=2.0)[source]

Scroll from the lower part to the upper part of the entire screen.

Parameters:
  • direction (str) – scrolling direction. “vertical” or “horizontal”
  • percent (float) – scrolling distance percentage of the entire screen height or width according to direction
  • duration (float) – time interval in which the action is performed
pinch(direction='in', percent=0.6, duration=2.0, dead_zone=0.1)[source]

Squeezing or expanding 2 fingers on the entire screen.

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 entire screen
  • duration (float) – time interval in which the action is performed
  • dead_zone (float) – pinching inner circle radius. should not be greater than percent
start_gesture(pos)[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(...)

# move from screen center to (0.6w, 0.6h) and hold for 1 second
# then return back to center
poco.start_gesture([0.5, 0.5]).to([0.6, 0.6]).hold(1).to([0.5, 0.5]).up()
Parameters:pos – starting coordinate of normalized coordinate system
Returns:an object for building serialized gesture action.
Return type:PendingGestureAction
apply_motion_tracks(tracks, accuracy=0.004)[source]

Similar to click but press the screen for the given time interval and then release

Parameters:
  • tracks (list) – list of poco.utils.track.MotionTrack object
  • accuracy (float) – motion accuracy for each motion steps in normalized coordinate metrics.
snapshot(width=720)[source]

Take the screenshot from the target device. The supported output format (png, jpg, etc.) depends on the agent implementation.

Parameters:
  • width (int) – an expected width of the screenshot. The real size depends on the agent implementation
  • might not be possible to obtain the expected width of the screenshot (and) –
Returns:

  • screen_shot (str/bytes): base64 encoded screenshot data
  • format (str): output format ‘png’, ‘jpg’, etc.

Return type:

2-tuple

get_screen_size()[source]

Get the real physical resolution of the screen of target device.

Returns:float number indicating the screen physical resolution in pixels
Return type:tuple
add_pre_action_callback(cb)[source]

Register a callback function to be invoked before each action (such as touch or swipe).

The callback function arguments are defined as follows:

  • action (str): name or tag of the action
  • proxy (UIObjectProxy or NoneType): related UI proxy which is involved in the action itself
  • args (tuple): all required arguments of the specific action function
Parameters:cb – the callback function
add_post_action_callback(cb)[source]

Register a callback function to be invoked after each action (such as touch or swipe).

The arguments to be passed are identical to the callback function in add_pre_action_callback.

Parameters:cb – the callback function