--- a/testing/marionette/client/marionette_driver/marionette.py
+++ b/testing/marionette/client/marionette_driver/marionette.py
@@ -39,26 +39,28 @@ class HTMLElement(object):
def __eq__(self, other_element):
return self.id == other_element.id
def find_element(self, method, target):
"""Returns an ``HTMLElement`` instance that matches the specified
method and target, relative to the current element.
- For more details on this function, see the `find_element` method
+ For more details on this function, see the
+ :func:`~marionette_driver.marionette.Marionette.find_element` method
in the Marionette class.
"""
return self.marionette.find_element(method, target, self.id)
def find_elements(self, method, target):
"""Returns a list of all ``HTMLElement`` instances that match the
specified method and target in the current context.
- For more details on this function, see the find_elements method
+ For more details on this function, see the
+ :func:`~marionette_driver.marionette.Marionette.find_elements` method
in the Marionette class.
"""
return self.marionette.find_elements(method, target, self.id)
def get_attribute(self, name):
"""Returns the requested attribute, or None if no attribute
is set.
"""
@@ -74,16 +76,17 @@ class HTMLElement(object):
return self.marionette._send_message("getElementProperty", body, key="value")
except errors.UnknownCommandException:
# Keep backward compatibility for code which uses get_attribute() to
# also retrieve element properties.
# Remove when Firefox 55 is stable.
return self.get_attribute(name)
def click(self):
+ """Simulates a click on the element."""
self.marionette._send_message("clickElement", {"id": self.id})
def tap(self, x=None, y=None):
"""Simulates a set of tap events on the element.
:param x: X coordinate of tap event. If not given, default to
the centre of the element.
:param y: Y coordinate of tap event. If not given, default to
@@ -242,17 +245,17 @@ class Actions(object):
element = element.id
self.action_chain.append(['press', element, x, y])
return self
def release(self):
'''
Sends a 'touchend' event to this element.
- May only be called if press() has already be called on this element.
+ May only be called if :func:`press` has already be called on this element.
If press and release are chained without a move action between them,
then it will be processed as a 'tap' event, and will dispatch the
expected mouse events ('mousemove' (if necessary), 'mousedown',
'mouseup', 'mouseclick') after the touch events. If there is a wait
period between press and release that will trigger a contextmenu,
then the 'contextmenu' menu event will be fired instead of the
touch/mouse events.
@@ -261,28 +264,28 @@ class Actions(object):
return self
def move(self, element):
'''
Sends a 'touchmove' event at the center of the target element.
:param element: Element to move towards.
- May only be called if press() has already be called.
+ May only be called if :func:`press` has already be called.
'''
element = element.id
self.action_chain.append(['move', element])
return self
def move_by_offset(self, x, y):
'''
Sends 'touchmove' event to the given x, y coordinates relative to the
top-left of the currently touched element.
- May only be called if press() has already be called.
+ May only be called if :func:`press` has already be called.
:param x: Specifies x-coordinate of move event, relative to the
top-left corner of the element.
:param y: Specifies y-coordinate of move event, relative to the
top-left corner of the element.
'''
self.action_chain.append(['moveByOffset', x, y])
return self
@@ -298,17 +301,17 @@ class Actions(object):
'''
self.action_chain.append(['wait', time])
return self
def cancel(self):
'''
Sends 'touchcancel' event to the target of the original 'touchstart' event.
- May only be called if press() has already be called.
+ May only be called if :func:`press` has already be called.
'''
self.action_chain.append(['cancel'])
return self
def tap(self, element, x=None, y=None):
'''
Performs a quick tap on the target element.
@@ -450,16 +453,17 @@ class Actions(object):
"""
self.action_chain.append(['keyDown', key_code])
return self
def key_up(self, key_code):
"""
Perform a "keyUp" action for the given key code. Modifier keys are
respected by the server for the course of an action chain.
+
:param key_up: The key to release as a result of this action.
"""
self.action_chain.append(['keyUp', key_code])
return self
def perform(self):
"""Sends the action chain built so far to the server side for
execution and clears the current chain of actions."""
@@ -860,16 +864,17 @@ class Marionette(object):
:param default_branch: Optional, if `True` the preference value will be read
from the default branch. Otherwise the user-defined
value if set is returned. Defaults to `False`.
:param value_type: Optional, XPCOM interface of the pref's complex value.
Defaults to `nsISupportsString`. Other possible values are:
`nsILocalFile`, and `nsIPrefLocalizedString`.
Usage example::
+
marionette.get_pref("browser.tabs.warnOnClose")
"""
with self.using_context(self.CONTEXT_CHROME):
pref_value = self.execute_script("""
Components.utils.import("resource://gre/modules/Preferences.jsm");
let pref = arguments[0];
@@ -889,16 +894,17 @@ class Marionette(object):
reset the preference to its default value. If no default
value exists, the preference will cease to exist.
:param default_branch: Optional, if `True` the preference value will
be written to the default branch, and will remain until
the application gets restarted. Otherwise a user-defined
value is set. Defaults to `False`.
Usage example::
+
marionette.set_pref("browser.tabs.warnOnClose", True)
"""
with self.using_context(self.CONTEXT_CHROME):
if value is None:
self.clear_pref(pref)
return
@@ -912,17 +918,17 @@ class Marionette(object):
prefs = new Preferences({defaultBranch: defaultBranch});
prefs.set(pref, value);
""", script_args=(pref, value, default_branch))
def set_prefs(self, prefs, default_branch=False):
"""Set the value of a list of preferences.
:param prefs: A dict containing one or more preferences and their values
- to be set. See `set_pref` for further details.
+ to be set. See :func:`set_pref` for further details.
:param default_branch: Optional, if `True` the preference value will
be written to the default branch, and will remain until
the application gets restarted. Otherwise a user-defined
value is set. Defaults to `False`.
Usage example::
marionette.set_prefs({"browser.tabs.warnOnClose": True})
@@ -931,17 +937,17 @@ class Marionette(object):
for pref, value in prefs.items():
self.set_pref(pref, value, default_branch=default_branch)
@contextmanager
def using_prefs(self, prefs, default_branch=False):
"""Set preferences for code executed in a `with` block, and restores them on exit.
:param prefs: A dict containing one or more preferences and their values
- to be set. See `set_prefs` for further details.
+ to be set. See :func:`set_prefs` for further details.
:param default_branch: Optional, if `True` the preference value will
be written to the default branch, and will remain until
the application gets restarted. Otherwise a user-defined
value is set. Defaults to `False`.
Usage example::
with marionette.using_prefs({"browser.tabs.warnOnClose": True}):
@@ -957,17 +963,17 @@ class Marionette(object):
self.set_prefs(original_prefs, default_branch=default_branch)
@do_process_check
def enforce_gecko_prefs(self, prefs):
"""Checks if the running instance has the given prefs. If not,
it will kill the currently running instance, and spawn a new
instance with the requested preferences.
- : param prefs: A dictionary whose keys are preference names.
+ :param prefs: A dictionary whose keys are preference names.
"""
if not self.instance:
raise errors.MarionetteException("enforce_gecko_prefs() can only be called "
"on Gecko instances launched by Marionette")
pref_exists = True
with self.using_context(self.CONTEXT_CHROME):
for pref, value in prefs.iteritems():
if type(value) is not str:
@@ -1058,17 +1064,17 @@ class Marionette(object):
self._send_message("quitApplication", body)
@do_process_check
def quit(self, in_app=False, callback=None):
"""Terminate the currently running instance.
This command will delete the active marionette session. It also allows
manipulation of eg. the profile data while the application is not running.
- To start the application again, start_session() has to be called.
+ To start the application again, :func:`start_session` has to be called.
:param in_app: If True, marionette will cause a quit from within the
browser. Otherwise the browser will be quit immediately
by killing the process.
:param callback: If provided and `in_app` is True, the callback will
be used to trigger the shutdown.
"""
if not self.instance:
@@ -1218,21 +1224,21 @@ class Marionette(object):
@test_name.setter
def test_name(self, test_name):
self._test_name = test_name
def delete_session(self, send_request=True, reset_session_id=False):
"""Close the current session and disconnect from the server.
:param send_request: Optional, if `True` a request to close the session on
- the server side will be send. Use `False` in case of eg. in_app restart()
+ the server side will be sent. Use `False` in case of eg. in_app restart()
or quit(), which trigger a deletion themselves. Defaults to `True`.
:param reset_session_id: Optional, if `True` the current session id will
- be reset, which will require an explicit call to `start_session()` before
- the test can continue. Defaults to `False`.
+ be reset, which will require an explicit call to :func:`start_session`
+ before the test can continue. Defaults to `False`.
"""
try:
if send_request:
self._send_message("deleteSession")
finally:
if reset_session_id:
self.session_id = None
self.session = None
@@ -1251,37 +1257,36 @@ class Marionette(object):
"""
return self.session
def set_script_timeout(self, timeout):
"""Sets the maximum number of ms that an asynchronous script is
allowed to run.
If a script does not return in the specified amount of time,
- a ScriptTimeoutException is raised.
+ a ``ScriptTimeoutException`` is raised.
:param timeout: The maximum number of milliseconds an asynchronous
- script can run without causing an ScriptTimeoutException to
+ script can run without causing an ``ScriptTimeoutException`` to
be raised
.. note:: `set_script_timeout` is deprecated, please use
`timeout.script` setter.
"""
warnings.warn(
"set_script_timeout is deprecated, please use timeout.script setter",
DeprecationWarning)
self.timeout.script = timeout / 1000
def set_search_timeout(self, timeout):
"""Sets a timeout for the find methods.
- When searching for an element using
- either :class:`Marionette.find_element` or
- :class:`Marionette.find_elements`, the method will continue
+ When searching for an element using either :func:`find_element` or
+ :func:`find_elements`, the method will continue
trying to locate the element for up to timeout ms. This can be
useful if, for example, the element you're looking for might
not exist immediately, because it belongs to a page which is
currently being loaded.
:param timeout: Timeout in milliseconds.
.. note:: `set_search_timeout` is deprecated, please use
@@ -1474,18 +1479,18 @@ class Marionette(object):
scope = self._send_message("getContext", key="value")
self.set_context(context)
try:
yield
finally:
self.set_context(scope)
def switch_to_alert(self):
- """Returns an Alert object for interacting with a currently
- displayed alert.
+ """Returns an :class:`~marionette_driver.marionette.Alert` object for
+ interacting with a currently displayed alert.
::
alert = self.marionette.switch_to_alert()
text = alert.text
alert.accept()
"""
return Alert(self)
@@ -1499,18 +1504,18 @@ class Marionette(object):
:param focus: A boolean value which determins whether to focus
the window that we just switched to.
"""
body = {"focus": focus, "name": window_id}
self._send_message("switchToWindow", body)
self.window = window_id
def get_active_frame(self):
- """Returns an HTMLElement representing the frame Marionette is
- currently acting on."""
+ """Returns an :class:`~marionette_driver.marionette.HTMLElement`
+ representing the frame Marionette is currently acting on."""
return self._send_message("getActiveFrame", key="value")
def switch_to_default_content(self):
"""Switch the current context to page's default content."""
return self.switch_to_frame()
def switch_to_parent_frame(self):
"""
@@ -1519,17 +1524,18 @@ class Marionette(object):
self._send_message("switchToParentFrame")
def switch_to_frame(self, frame=None, focus=True):
"""Switch the current context to the specified frame. Subsequent
commands will operate in the context of the specified frame,
if applicable.
:param frame: A reference to the frame to switch to. This can
- be an ``HTMLElement``, an integer index, string name, or an
+ be an :class:`~marionette_driver.marionette.HTMLElement`,
+ an integer index, string name, or an
ID attribute. If you call ``switch_to_frame`` without an
argument, it will switch to the top-level frame.
:param focus: A boolean value which determins whether to focus
the frame that we just switched to.
"""
body = {"focus": focus}
if isinstance(frame, HTMLElement):
@@ -1539,19 +1545,19 @@ class Marionette(object):
self._send_message("switchToFrame", body)
def switch_to_shadow_root(self, host=None):
"""Switch the current context to the specified host's Shadow DOM.
Subsequent commands will operate in the context of the specified Shadow
DOM, if applicable.
:param host: A reference to the host element containing Shadow DOM.
- This can be an ``HTMLElement``. If you call
- ``switch_to_shadow_root`` without an argument, it will switch to the
- parent Shadow DOM or the top-level frame.
+ This can be an :class:`~marionette_driver.marionette.HTMLElement`.
+ If you call ``switch_to_shadow_root`` without an argument, it will
+ switch to the parent Shadow DOM or the top-level frame.
"""
body = {}
if isinstance(host, HTMLElement):
body["id"] = host.id
return self._send_message("switchToShadowRoot", body)
def get_url(self):
"""Get a string representing the current URL.
@@ -1586,20 +1592,20 @@ class Marionette(object):
The command will return with a failure if there is an error
loading the document or the URL is blocked. This can occur if
it fails to reach the host, the URL is malformed, the page is
restricted (about:* pages), or if there is a certificate issue
to name some examples.
The document is considered successfully loaded when the
`DOMContentLoaded` event on the frame element associated with the
- `window` triggers and `document.readState` is "complete".
+ `window` triggers and `document.readyState` is "complete".
In chrome context it will change the current `window`'s location
- to the supplied URL and wait until `document.readState` equals
+ to the supplied URL and wait until `document.readyState` equals
"complete" or the page timeout duration has elapsed.
:param url: The URL to navigate to.
"""
self._send_message("get", {"url": url})
def go_back(self):
"""Causes the browser to perform a back navigation."""
@@ -1667,18 +1673,18 @@ class Marionette(object):
return self._from_json(rv)
def execute_script(self, script, script_args=(), new_sandbox=True,
sandbox="default", script_timeout=None):
"""Executes a synchronous JavaScript script, and returns the
result (or None if the script does return a value).
The script is executed in the context set by the most recent
- set_context() call, or to the CONTEXT_CONTENT context if set_context()
- has not been called.
+ :func:`set_context` call, or to the CONTEXT_CONTENT context if
+ :func:`set_context` has not been called.
:param script: A string containing the JavaScript to execute.
:param script_args: An interable of arguments to pass to the script.
:param sandbox: A tag referring to the sandbox you wish to use;
if you specify a new tag, a new sandbox will be created.
If you use the special tag `system`, the sandbox will
be created using the system principal which has elevated
privileges.
@@ -1714,17 +1720,17 @@ class Marionette(object):
window.wrappedJSObject.test1 = "foo";
window.wrappedJSObject.test2 = "bar";
return window.wrappedJSObject.test1 + window.wrappedJSObject.test2;
''')
assert result == "foobar"
Global variables set by individual scripts do not persist between
script calls by default. If you wish to persist data between
- script calls, you can set new_sandbox to False on your next call,
+ script calls, you can set `new_sandbox` to False on your next call,
and add any new variables to a new 'global' object like this:
::
marionette.execute_script("global.test1 = 'foo';")
result = self.marionette.execute_script("return global.test1;", new_sandbox=False)
assert result == "foo"
@@ -1744,18 +1750,18 @@ class Marionette(object):
def execute_async_script(self, script, script_args=(), new_sandbox=True,
sandbox="default", script_timeout=None,
debug_script=False):
"""Executes an asynchronous JavaScript script, and returns the
result (or None if the script does return a value).
The script is executed in the context set by the most recent
- set_context() call, or to the CONTEXT_CONTENT context if
- set_context() has not been called.
+ :func:`set_context` call, or to the CONTEXT_CONTENT context if
+ :func:`set_context` has not been called.
:param script: A string containing the JavaScript to execute.
:param script_args: An interable of arguments to pass to the script.
:param sandbox: A tag referring to the sandbox you wish to use; if
you specify a new tag, a new sandbox will be created. If you
use the special tag `system`, the sandbox will be created
using the system principal which has elevated privileges.
:param new_sandbox: If False, preserve global variables from
@@ -1787,25 +1793,28 @@ class Marionette(object):
"scriptTimeout": script_timeout,
"line": int(frame[1]),
"filename": os.path.basename(frame[0]),
"debug_script": debug_script}
rv = self._send_message("executeAsyncScript", body, key="value")
return self._from_json(rv)
def find_element(self, method, target, id=None):
- """Returns an HTMLElement instances that matches the specified
- method and target in the current context.
+ """Returns an :class:`~marionette_driver.marionette.HTMLElement`
+ instance that matches the specified method and target in the current
+ context.
- An HTMLElement instance may be used to call other methods on the
- element, such as click(). If no element is immediately found, the
- attempt to locate an element will be repeated for up to the amount of
- time set by ``timeout.implicit``. If multiple elements match the given
- criteria, only the first is returned. If no element matches, a
- NoSuchElementException will be raised.
+ An :class:`~marionette_driver.marionette.HTMLElement` instance may be
+ used to call other methods on the element, such as
+ :func:`~marionette_driver.marionette.HTMLElement.click`. If no element
+ is immediately found, the attempt to locate an element will be repeated
+ for up to the amount of time set by
+ :attr:`marionette_driver.timeout.Timeouts.implicit`. If multiple
+ elements match the given criteria, only the first is returned. If no
+ element matches, a ``NoSuchElementException`` will be raised.
:param method: The method to use to locate the element; one of:
"id", "name", "class name", "tag name", "css selector",
"link text", "partial link text", "xpath", "anon" and "anon
attribute". Note that the "name", "link text" and "partial
link test" methods are not supported in the chrome DOM.
:param target: The target of the search. For example, if method =
"tag", target might equal "div". If method = "id", target would
@@ -1814,23 +1823,26 @@ class Marionette(object):
with the specified id.
"""
body = {"value": target, "using": method}
if id:
body["element"] = id
return self._send_message("findElement", body, key="value")
def find_elements(self, method, target, id=None):
- """Returns a list of all HTMLElement instances that match the
- specified method and target in the current context.
+ """Returns a list of all
+ :class:`~marionette_driver.marionette.HTMLElement` instances that match
+ the specified method and target in the current context.
- An HTMLElement instance may be used to call other methods on the
- element, such as click(). If no element is immediately found,
- the attempt to locate an element will be repeated for up to the
- amount of time set by ``timeout.implicit``.
+ An :class:`~marionette_driver.marionette.HTMLElement` instance may be
+ used to call other methods on the element, such as
+ :func:`~marionette_driver.marionette.HTMLElement.click`. If no element
+ is immediately found, the attempt to locate an element will be repeated
+ for up to the amount of time set by
+ :attr:`marionette_driver.timeout.Timeouts.implicit`.
:param method: The method to use to locate the elements; one
of: "id", "name", "class name", "tag name", "css selector",
"link text", "partial link text", "xpath", "anon" and "anon
attribute". Note that the "name", "link text" and "partial link
test" methods are not supported in the chrome DOM.
:param target: The target of the search. For example, if method =
"tag", target might equal "div". If method = "id", target would be
@@ -1951,18 +1963,19 @@ class Marionette(object):
as a base 64 string by default. If the `element` argument is defined the
capture area will be limited to the bounding box of that
element. Otherwise, the capture area will be the bounding box
of the current frame.
:param element: The element to take a screenshot of. If None, will
take a screenshot of the current frame.
- :param highlights: A list of HTMLElement objects to draw a red
- box around in the returned screenshot.
+ :param highlights: A list of
+ :class:`~marionette_driver.marionette.HTMLElement` objects to draw
+ a red box around in the returned screenshot.
:param format: if "base64" (the default), returns the screenshot
as a base64-string. If "binary", the data is decoded and
returned as raw binary. If "hash", the data is hashed using
the SHA-256 algorithm and the result is returned as a hex digest.
:param full: If True (the default), the capture area will be the
complete frame. Else only the viewport is captured. Only applies
@@ -2053,17 +2066,17 @@ class Marionette(object):
"""
warnings.warn("set_window_size() has been deprecated, please use set_window_rect()",
DeprecationWarning)
body = {"width": width, "height": height}
return self._send_message("setWindowSize", body)
def maximize_window(self):
""" Resize the browser window currently receiving commands. The action
- should be equivalent to the user pressing the the maximize button
+ should be equivalent to the user pressing the maximize button
"""
return self._send_message("maximizeWindow")
def fullscreen(self):
""" Synchronously sets the user agent window to full screen as if the user
had done "View > Enter Full Screen", or restores it if it is already
in full screen.
