poco.pocofw module
- class Poco(agent, **options)[源代码]
-
Poco standard initializer.
- 参数:
agent (
PocoAgent
) – an agent object for Poco to communicate with the target device. SeePocoAgent
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, thePocoNoSuchNodeException
is raisedtouch_down_duration
: Touch down step duration of the click operation last for. If this argument is provided, this value will set toself.agent.input
module. Note that not all implementation of poco support this parameter. If not support, you may see a warning.reevaluate_volatile_attributes
: Re-select target UI proxy when retrieving volatile attributes. Poco drivers that using hrpc connections should default to beFalse
as hrpc always reevaluate the attributes remotely. This option is useful forStdPoco
driver and should be handled byStdPoco
.
- __call__(name=None, **kw)[源代码]
Call Poco instance to select the UI element by query expression. Query expression can contain specific name and/or other attributes. Invisible UI elements will be skipped even if “visible=False” argument is set.
Selection process is not executed instantly, the query expression is stored in the UI proxy and the selection is executed only then when the UI element(s) info is required (such get the point coordinates where to click, and/or retrieve the specific attribute value).
示例
This example shows selecting a Button named ‘close’:
poco = Poco(...) close_btn = poco('close', type='Button')
- 参数:
name (
str
) – name of the UI element to be selected- 关键字参数:
xx – arbitrary key value pair that stands for selecting the UI matching the value of
UI.xx
xxMatches (
str
) – arbitrary key value pair that stands for selecting the UI matching the regular expression patternUI.xx
In keyword args, you can only use xx or xxMatches at the same time. Using both with the same attribute does not make sense. Besides, xx should not start with
_
(underscore) as attributes start with_
are private attributes that used by sdk implementation.# select the UI element(s) which text attribute matches the pattern '^close.*$' poco = Poco(...) arb_close_btn = poco(textMatches='^close.*$')
- 返回:
UI proxy object representing the UI element matches the given query expression.
- 返回类型:
- add_post_action_callback(cb)[源代码]
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
.- 参数:
cb – the callback function
- add_pre_action_callback(cb)[源代码]
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 actionproxy
(UIObjectProxy
orNoneType
): related UI proxy which is involved in the action itselfargs
(tuple
): all required arguments of the specific action function
- 参数:
cb – the callback function
- property agent
Readonly property to access poco agent instance. See
poco.agent.PocoAgent
for more details.- 返回:
poco agent instance
- 返回类型:
- apply_motion_tracks(tracks, accuracy=0.004)[源代码]
Similar to click but press the screen for the given time interval and then release
- 参数:
tracks (
list
) – list ofpoco.utils.track.MotionTrack
objectaccuracy (
float
) – motion accuracy for each motion steps in normalized coordinate metrics.
- click(pos)[源代码]
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.示例
Click the point of
(100, 100)
of screen which resolution is(1920, 1080)
:poco.click([100.0 / 1920, 100.0 / 1080])
- 参数:
pos (
list(float, float)
/tuple(float, float)
) – coordinates (x, y) in range of 0 to 1- 抛出:
InvalidOperationException – when clicked outside of the screen
- dump()[源代码]
Dump the current UI tree of the target device. The output format depends on the agent implementation.
- 返回:
base64 encoded UI tree data
- 返回类型:
str
- freeze()[源代码]
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 callingdump
function from frozen poco. See the example below.示例
poco = Poco(...) frozen_poco = poco.freeze() hierarchy_dict = frozen_poco.agent.hierarchy.dump() # will return the already cached hierarchy data
- 返回:
new poco instance copy from current poco instance (
self
)- 返回类型:
- get_screen_size()[源代码]
Get the real physical resolution of the screen of target device.
- 返回:
float number indicating the screen physical resolution in pixels
- 返回类型:
tuple
- long_click(pos, duration=2.0)[源代码]
Similar to click but press the screen for the given time interval and then release
- 参数:
pos (
2-list/2-tuple
) – coordinates (x, y) in range from 0 to 1duration – duration of press the screen
- pinch(direction='in', percent=0.6, duration=2.0, dead_zone=0.1)[源代码]
Squeezing or expanding 2 fingers on the entire screen.
- 参数:
direction (
str
) – pinching direction, only “in” or “out”. “in” for squeezing, “out” for expandingpercent (
float
) – squeezing range from or expanding range to of the entire screenduration (
float
) – time interval in which the action is performeddead_zone (
float
) – pinching inner circle radius. should not be greater thanpercent
- scroll(direction='vertical', percent=0.6, duration=2.0)[源代码]
Scroll from the lower part to the upper part of the entire screen.
- 参数:
direction (
str
) – scrolling direction. “vertical” or “horizontal”percent (
float
) – scrolling distance percentage of the entire screen height or width according to directionduration (
float
) – time interval in which the action is performed
- sleep_for_polling_interval()[源代码]
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.
- snapshot(width=720)[源代码]
Take the screenshot from the target device. The supported output format (png, jpg, etc.) depends on the agent implementation.
- 参数:
width (
int
) – an expected width of the screenshot. The real size depends on the agent implementationscreenshot (and might not be possible to obtain the expected width of the) –
- 返回:
screen_shot (
str/bytes
): base64 encoded screenshot dataformat (
str
): output format ‘png’, ‘jpg’, etc.
- 返回类型:
2-tuple
- start_gesture(pos)[源代码]
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(...) # 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()
- 参数:
pos – starting coordinate of normalized coordinate system
- 返回:
an object for building serialized gesture action.
- 返回类型:
PendingGestureAction
- swipe(p1, p2=None, direction=None, duration=2.0)[源代码]
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.示例
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])
- 参数:
p1 (
2-list/2-tuple
) – start pointp2 – end point
direction – swipe direction
duration (
float
) – time interval in which the swipe action is performed
- 抛出:
InvalidOperationException – when the start point of the swipe action lies outside the screen
- use_render_resolution(use=True, resolution=None)[源代码]
Whether to use render resolution
- 参数:
use – True or false
resolution – render resolution in portrait mode, offset_x, offset_y, offset_width, offset_height, (0, 10, 1080, 1820)
- wait_for_all(objects, timeout=120)[源代码]
Wait until all of given UI proxies show up before timeout. All UI proxies will be polled periodically. See option
poll_interval
inPoco
’s initialization for more details.- 参数:
objects (Iterable<
UIObjectProxy
>) – iterable object of the given UI proxiestimeout (
float
) – timeout in seconds, default is 120s
- 抛出:
PocoTargetTimeout – when not all of UI proxies appeared before timeout
- wait_for_any(objects, timeout=120)[源代码]
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
inPoco
’s initialization for more details.- 参数:
objects (Iterable<
UIObjectProxy
>) – iterable object of the given UI proxiestimeout (
float
) – timeout in seconds, default is 120s
- 返回:
the first appeared UI proxy
- 返回类型:
- 抛出:
PocoTargetTimeout – when none of UI proxies appeared before timeout