API

WebDriver

class macaca.webdriver.WebDriver(desired_capabilities, url='http://127.0.0.1:3456/wd/hub')[source]

Bases: object

The WebDriver Object to implement most part of WebDriver protocol.

session_id

str – A UDID used to uniquely identify each session.

capabilities

dict – The capabilities of the driver/browserreturned by remote server.

desired_capabilities

dict – The desired capabilities requested by the local end.

remote_invoker

RemoteInvoker – The remote invoker responsible for send request.

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

Accepts the alert available.

Support:
iOS

Set a cookie.

Support:
Web(WebView)
Parameters:cookie_dict – A dictionary contain keys: “name”, “value”, [“path”], [“domain”], [“secure”], [“httpOnly”], [“expiry”].
Returns:WebElement Object.
alert_keys(*args, **kwargs)[source]

Sends keystrokes to a JavaScript prompt() dialog.

Support:
iOS
Parameters:keys (str) – The keys send to.
alert_text

Gets the text of the Alert.

Support:
iOS
attach(*args, **kwargs)[source]

Attach to given Session.

Support:
Android iOS Web(WebView)
Parameters:session_id (str) – The given session ID
Returns:WebDriver Object.
back(*args, **kwargs)[source]

Back.

Support:
Web(WebView)
Returns:WebDriver Object.
close(*args, **kwargs)[source]

Closes the current window.

Support:
Web(WebView)
Returns:WebDriver Object.
context

returns the current context (Native or WebView).

Support:
Android iOS
contexts

returns a list of available contexts

Support:
Android iOS
cookies

Returns all cookies associated with the address of the current context.

Support:
Web(WebView)
current_url

Gets the URL of the current page.

Support:
Web(WebView)
Returns:Return the URL of the current page.
current_window_handle

Returns the handle of the current window.

Support:
Web(WebView)
delete_all_cookies(*args, **kwargs)[source]

Delete all cookies at once.

Support:
Web(WebView)

Delete a single cookie by name.

Support:
Web(WebView)
Parameters:name – The cookie name.
dismiss_alert(*args, **kwargs)[source]

Dismisses the alert available.

Support:
iOS
element(using, value)[source]

Find an element in the current context.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

WebElement Object.
Raises:

WebDriverException.
element_if_exists(using, value)[source]

Check if an element in the current context.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

Return True if the element does exists and return False otherwise.
Raises:

WebDriverException.
element_or_none(using, value)[source]

Check if an element in the current context.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

Return Element if the element does exists and return None otherwise.
Raises:

WebDriverException.
elements(using, value)[source]

Find elements in the current context.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

Return a List<Element | None>, if no element matched, the list is empty.
Raises:

WebDriverException.
execute_async_script(*args, **kwargs)[source]

Execute JavaScript Asynchronously in current context.

Support:
Web(WebView)
Parameters:
  • script – The JavaScript to execute.
  • *args – Arguments for your JavaScript.
Returns:

Returns the return value of the function.
execute_script(script, *args)[source]

Execute JavaScript Synchronously in current context.

Support:
Web(WebView)
Parameters:
  • script – The JavaScript to execute.
  • *args – Arguments for your JavaScript.
Returns:

Returns the return value of the function.
flick(*args, **kwargs)[source]
Deprecated use touch(‘drag’, { fromX, fromY, toX, toY, duration(s) }) instead.
Flick on the touch screen using finger motion events. This flickcommand starts at a particulat screen location.
Support:
iOS
Parameters:
  • element (WebElement) – WebElement Object where the flick starts.
  • x(float} – The x offset in pixels to flick by.
  • y (float) – The y offset in pixels to flick by.
  • speed (float) –
Returns:

WebDriver object.
forward(*args, **kwargs)[source]

Forward.

Support:
Web(WebView)
Returns:WebDriver Object.
get(*args, **kwargs)[source]

Loads a web page in the current browser session.

Support:
Web(WebView)
Parameters:url (str) – The URL to navigate to.
Returns:WebDriver Object.
Raises:WebDriverException.
get_active_element()[source]

Returns the active element in current context.

Support:
Web(WebView)

Get a single cookie by name.

Support:
Web(WebView)
Returns:Returns the cookie if found, None if not.
get_window_position(window_handle='current')[source]

Gets the x,y position of the current window.

Support:
Web(WebView)
Parameters:window_handle (str) – Identifier of window_handle, default to ‘current’.
Usage:
driver.get_window_position()
get_window_size(window_handle='current')[source]

Gets the width and height of the current window.

Support:
Web(WebView)
Parameters:window_handle (str) – Identifier of window_handle, default to ‘current’.
Returns:A dict contains width and height
init(*args, **kwargs)[source]

Create Session by desiredCapabilities

Support:
Android iOS Web(WebView)
Returns:WebDriver Object.
keys(*args, **kwargs)[source]

Send a sequence of key strokes.

Support:
Android iOS Web(WebView)
Parameters:value (str|int|list) – value can be a string, int or a list contains defined Keys.
maximize_window(*args, **kwargs)[source]

Maximizes the current window.

Support:
Web(WebView)
Returns:WebDriver Object.
move_to(*args, **kwargs)[source]
Deprecated use element.touch(‘drag’, { toX, toY, duration(s) }) instead.
Move the mouse by an offset of the specificed element.
Support:
Android
Parameters:
  • element (WebElement) – WebElement Object.
  • x (float) – X offset to move to, relative to the top-left corner of the element.
  • y (float) – Y offset to move to, relative to the top-left corner of the element.
Returns:

WebDriver object.
quit(*args, **kwargs)[source]

Quit the driver.

Support:
Android iOS Web(WebView)
Returns:WebDriver Object.
refresh(*args, **kwargs)[source]

Refresh.

Support:
Web(WebView)
Returns:WebDriver Object.
save_screenshot(*args, **kwargs)[source]

Save the screenshot to local.

Support:
Android iOS Web(WebView)
Parameters:
  • filename (str) – The path to save the image.
  • quietly (bool) – If True, omit the IOError when failed to save the image.
Returns:

WebElement Object.
Raises:
  • WebDriverException.
  • IOError.
send_keys(*args, **kwargs)[source]

Send a sequence of key strokes.

Support:
Android iOS Web(WebView)
Parameters:value (str|int|list) – value can be a string, int or a list contains defined Keys.
sessions

Gets all the sessions of the webdriver server.

Support:
Android iOS Web(WebView)
Returns:Return the URL of the current page.
set_implicitly_wait(*args, **kwargs)[source]
Implicit wait timeout that specifies a time to
wait for the implicit element location strategy hen locating elements using Find Element and Find Elements.
Support:
Android iOS Web(WebView)
Parameters:time_to_wait (int) – Amount of time to wait (in seconds)
Returns:WebElement Object.
set_page_load_timeout(*args, **kwargs)[source]
Page load timeout that specifies a time to
wait for the page loading to complete.
Support:
Web(WebView)
Parameters:time_to_wait (int) – Amount of time to wait
Returns:WebElement Object.
set_script_timeout(*args, **kwargs)[source]

Script timeout that specifies a time to wait for scripts to run.

Support:
Web(WebView)
Parameters:time_to_wait (int) – Amount of time to wait (in seconds)
Returns:WebElement Object.
set_window_position(*args, **kwargs)[source]

Sets the x,y position of the current window.

Support:
Web(WebView)
Parameters:
  • x (int) – the x-coordinate in pixels.
  • y (int) – the y-coordinate in pixels.
  • window_handle (str) – Identifier of window_handle, default to ‘current’.
Returns:

WebDriver Object.
set_window_size(*args, **kwargs)[source]

Sets the width and height of the current window.

Support:
Web(WebView)
Parameters:
  • width (int) – the width in pixels.
  • height (int) – the height in pixels.
  • window_handle (str) – Identifier of window_handle, default to ‘current’.
Returns:

WebDriver Object.
source

Gets the source of the current page.

Support:
Android iOS Web(WebView)
Returns:Return the source of the current page.
switch_to_frame(*args, **kwargs)[source]

Switches focus to the specified frame, by index, name, or webelement.

Support:
Web(WebView)
Parameters:frame_reference (None|int|WebElement) – The identifier of the frame to switch to. None means to set to the default context. An integer representing the index. A webelement means that is an (i)frame to switch to. Otherwise throw an error.
Returns:WebDriver Object.
switch_to_parent_frame(*args, **kwargs)[source]

Switches focus to the parent context.

Support:
Web(WebView)
switch_to_window(*args, **kwargs)[source]

Switch to the given window.

Support:
Web(WebView)
Parameters:window_name (str) – The window to change focus to.
Returns:WebDriver Object.
take_screenshot()[source]
Gets the screenshot of the current window
as a base64 encoded string.
Support:
Android iOS Web(WebView)
Returns:Base64 encoded string of the screenshot.
tap(*args, **kwargs)[source]
Deprecated use element.touch(‘tap’) instead.
Single tap on the touch enabled device.
Support:
Android iOS
Parameters:element (WebElement) – WebElement Object to single tap on.
Returns:WebDriver object.
title

Get the current page title.

Support:
Web(WebView)
touch(*args, **kwargs)[source]
Apply touch actions on devices. Such as, tap/doubleTap/press/pinch/rotate/drag.
See more on https://github.com/alibaba/macaca/issues/366.
Support:
Android iOS
Parameters:
  • name (str) – Name of the action
  • args (dict) – Arguments of the action
Returns:

WebDriver Object.
Raises:

WebDriverException.
wait_for(timeout=10000, interval=1000, asserter=<function <lambda>>)[source]

Wait for driver till satisfy the given condition

Support:
Android iOS Web(WebView)
Parameters:
  • timeout (int) – How long we should be retrying stuff.
  • interval (int) – How long between retries.
  • asserter (callable) – The asserter func to determine the result.
Returns:

Return the driver.
Raises:

WebDriverException.
wait_for_element(using, value, timeout=10000, interval=1000, asserter=<function is_displayed>)[source]

Wait for element till satisfy the given condition

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
  • timeout (int) – How long we should be retrying stuff.
  • interval (int) – How long between retries.
  • asserter (callable) – The asserter func to determine the result.
Returns:

Return the Element.
Raises:

WebDriverException.
wait_for_elements(using, value, timeout=10000, interval=1000, asserter=<function is_displayed>)[source]

Wait for elements till satisfy the given condition

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
  • timeout (int) – How long we should be retrying stuff.
  • interval (int) – How long between retries.
  • asserter (callable) – The asserter func to determine the result.
Returns:

Return the list of Element if any of them satisfy the condition.
Raises:

WebDriverException.
window_handles

Returns the handles of all windows within the current session.

Support:
Web(WebView)

WebElement

class macaca.webelement.WebElement(element_id, driver)[source]

Bases: object

The WebElement Object to implement most part of WebDriver protocol.

element_id

str – A UDID used to uniquely identify an element.

clear(*args, **kwargs)[source]
The Element Clear command scrolls into view
a submittable element excluding buttons or editable element, and then attempts to clear its value, checkedness, or text content.
Support:
Android iOS Web(WebView)
click(*args, **kwargs)[source]
The Element Click command scrolls into view
the element and then attempts to click the centre of the visible area of the first element of the DOMRect sequence. In case the element is not displayed, an element not visible error is returned.
Support:
Android iOS Web(WebView)
driver

Internal reference to the WebDriver instance.

element(using, value)[source]

find an element in the current element.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

WebElement Object.
Raises:

WebDriverException.
element_if_exists(using, value)[source]

Check if an element in the current element.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

Return True if the element does exists and return False otherwise.
Raises:

WebDriverException.
element_or_none(using, value)[source]

Check if an element in the current element.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

Return Element if the element does exists and return None otherwise.
Raises:

WebDriverException.
elements(using, value)[source]

find elements in the current element.

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
Returns:

Return a List<Element | None>, if no element matched, the list is empty.
Raises:

WebDriverException.
flick(*args, **kwargs)[source]
Deprecated use touch(‘drag’, { fromX, fromY, toX, toY, duration(s) }) instead.
Flick on the touch screen using finger motion events. This flickcommand starts at a particulat screen location.
Support:
iOS
Parameters:
  • x(float} – The x offset in pixels to flick by.
  • y (float) – The y offset in pixels to flick by.
  • speed (float) –
Returns:

WebElement object.
get_computed_css(property_name)[source]
The computed value of the given CSS property
of the given web element.
Support:
Support: Web(WebView)
Parameters:property_name (str) – CSS property.
Returns:The computed value of parameter property name from element’s style declarations if the current browsing context’s document type is not “xml”, else let it be “”
get_property(name)[source]

Return the result of getting a property, Support: Android iOS Web(WebView).

Support:
Support: Android iOS Web(WebView)
Parameters:name (str) – Name of the property to retrieve, Android iOS can only get origin size.
Returns:The property of the element.
is_displayed()[source]

Whether the element is visible.

Support:
Android Web(WebView)
is_enabled()[source]

Returns whether the element is enabled.

Support:
Web(WebView)
is_selected()[source]

Returns whether the element is selected.

Support:
Web(WebView)
keys(*args, **kwargs)[source]

Send a sequence of key strokes to an element.

Support:
Android iOS Web(WebView)
Parameters:value (str|int|list) – value can be a string, int or a list contains defined Keys.
move_to(*args, **kwargs)[source]
Deprecated use element.touch(‘drag’, { toX, toY, duration(s) }) instead.
Move the mouse by an offset of the specificed element.
Support:
Android
Parameters:
  • x (float) – X offset to move to, relative to the top-left corner of the element.
  • y (float) – Y offset to move to, relative to the top-left corner of the element.
Returns:

WebElement object.
rect

The dimensions and coordinates of the given web element in pixels.

Support:
Android iOS Web(WebView)
Returns:x(float): X axis position of the top-left corner. y(float): Y axis position of the top-left corner. height(float): Height of the web element’s bounding rectangle. width(float): Width of the web element’s bounding rectangle.
Return type:A dict contains
save_screenshot(*args, **kwargs)[source]

Save the screenshot to local.

Support:
Android iOS Web(WebView)
Parameters:
  • filename (str) – The path to save the image.
  • quietly (bool) – If True, omit the IOError when failed to save the image.
Returns:

WebElement Object.
Raises:
  • WebDriverException.
  • IOError.
send_keys(*args, **kwargs)[source]

Send a sequence of key strokes to an element.

Support:
Android iOS Web(WebView)
Parameters:value (str|int|list) – value can be a string, int or a list contains defined Keys.
size

The size of the given web element in pixels.

Support:
Web(WebView)
Returns:height(float): Height of the web element’s bounding rectangle. width(float): Width of the web element’s bounding rectangle.
Return type:A dict contains
tag_name

Return the tagName of the element.

Support:
Web(WebView)
take_screenshot()[source]
Gets the screenshot of the current element
as a base64 encoded string.
Support:
Android iOS Web(WebView)
Returns:Base64 encoded string of the screenshot.
tap(*args, **kwargs)[source]
Deprecated use touch(‘tap’) instead.
Single tap on the touch enabled device.
Support:
Android iOS
Parameters:element (WebElement) – WebElement Object to single tap on.
Returns:WebElement object.
text
Return the text of the element.
This is equivalent to calling element.innerText.
Support:
Android iOS Web(WebView)
touch(*args, **kwargs)[source]
Apply touch actions on devices. Such as, tap/doubleTap/press/pinch/rotate/drag.
See more on https://github.com/alibaba/macaca/issues/366.
Support:
Android iOS
Parameters:
  • name (str) – Name of the action
  • args (dict) – Arguments of the action
Returns:

WebDriver Object.
Raises:

WebDriverException.
wait_for(timeout=10000, interval=1000, asserter=<function <lambda>>)[source]

Wait for element till given condition

Support:
Android iOS Web(WebView)
Parameters:
  • timeout (int) – How long we should be retrying stuff.
  • interval (int) – How long between retries.
  • asserter (callable) – The asserter func to determine the result.
Returns:

Return the Element.
Raises:

WebDriverException.
wait_for_element(using, value, timeout=10000, interval=1000, asserter=<function is_displayed>)[source]

Wait for element till the given condition

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
  • timeout (int) – How long we should be retrying stuff.
  • interval (int) – How long between retries.
  • asserter (callable) – The asserter func to determine the result.
Returns:

Return the Element.
Raises:

WebDriverException.
wait_for_elements(using, value, timeout=10000, interval=1000, asserter=<function is_displayed>)[source]

Wait for elements till the given condition

Support:
Android iOS Web(WebView)
Parameters:
  • using (str) – The element location strategy.
  • value (str) – The value of the location strategy.
  • timeout (int) – How long we should be retrying stuff.
  • interval (int) – How long between retries.
  • asserter (callable) – The asserter func to determine the result.
Returns:

Return the list of Element if any of them satisfy the condition.
Raises:

WebDriverException.

Asserters

macaca.asserters.is_displayed(target)[source]

Assert whether the target is displayed

Parameters:target (WebElement) – WebElement Object.
Returns:Return True if the element is displayed or return False otherwise.
macaca.asserters.is_not_displayed(target)[source]

Assert whether the target is not displayed

Parameters:target (WebElement) – WebElement Object.
Returns:Return True if the element is not displayed or return False otherwise.

Keys

class macaca.keys.Keys(*args, **kwargs)[source]

Bases: sphinx.ext.autodoc.importer._MockObject

The Unicode Private Use Area code points, 0xE000-0xF8FF, are used to represent pressable, non-text keys.

ADD = u'\ue025'
ALT = u'\ue00a'
ARROW_DOWN = u'\ue015'
ARROW_LEFT = u'\ue012'
ARROW_RIGHT = u'\ue014'
ARROW_UP = u'\ue013'
BACK = u'\ue106'
BACKSPACE = u'\ue003'
CALL = u'\ue109'
CAMERA = u'\ue108'
CANCEL = u'\ue001'
CLEAR = u'\ue005'
COMMAND = u'\ue03d'
CONTROL = u'\ue009'
DECIMAL = u'\ue028'
DELETE = u'\ue017'
DIVIDE = u'\ue029'
DPAD_CENTER = u'\ue110'
DPAD_DOWN = u'\ue10f'
DPAD_LEFT = u'\ue10c'
DPAD_RIGHT = u'\ue10e'
DPAD_UP = u'\ue10d'
END = u'\ue010'
END_CALL = u'\ue10a'
ENTER = u'\ue007'
EQUALS = u'\ue019'
ESCAPE = u'\ue00c'
F1 = u'\ue031'
F10 = u'\ue03a'
F11 = u'\ue03b'
F12 = u'\ue03c'
F2 = u'\ue032'
F3 = u'\ue033'
F4 = u'\ue034'
F5 = u'\ue035'
F6 = u'\ue036'
F7 = u'\ue037'
F8 = u'\ue038'
F9 = u'\ue039'
HELP = u'\ue002'
HOME = u'\ue011'
HOME_SCREEN = u'\ue105'
INSERT = u'\ue016'
MENU = u'\ue107'
META = u'\ue03d'
MULTIPLY = u'\ue024'
NULL = u'\ue000'
NUMPAD0 = u'\ue01a'
NUMPAD1 = u'\ue01b'
NUMPAD2 = u'\ue01c'
NUMPAD3 = u'\ue01d'
NUMPAD4 = u'\ue01e'
NUMPAD5 = u'\ue01f'
NUMPAD6 = u'\ue020'
NUMPAD7 = u'\ue021'
NUMPAD8 = u'\ue022'
NUMPAD9 = u'\ue023'
PAGE_DOWN = u'\ue00f'
PAGE_UP = u'\ue00e'
PAUSE = u'\ue00b'
POWER = u'\ue101'
RETURN = u'\ue006'
SEARCH = u'\ue10b'
SEMICOLON = u'\ue018'
SEPARATOR = u'\ue026'
SHIFT = u'\ue008'
SPACE = u'\ue00d'
SUBTRACT = u'\ue027'
TAB = u'\ue004'
VOLUME_DOWN = u'\ue103'
VOLUME_MUTE = u'\ue104'
VOLUME_UP = u'\ue102'
ZENKAKU_HANKAKU = u'\ue040'

WebDriverException

exception macaca.webdriverexception.WebDriverException(error=None, message=None, screen=None, stacktrace=None)[source]

Bases: exceptions.Exception

WebDriver exception.

error

str – Error type defined in WebDriver Protocol.

message

str – A description of the kind of error that occurred.

screen

str – If included, a screenshot of the current page as a base64 encoded string.

stacktrace

str – A stack trace report of the error occurred.