Marionette

  • Revision slug: Marionette/Marionette
  • Revision title: Marionette
  • Revision id: 372439
  • Created:
  • Creator: Ann_Yiming
  • Is current revision? No
  • Comment

Revision Content

Every Python test for Marionette has an instance of the Marionette class bound to self.marionette.  This instance contains most of the methods used to interact with gecko.

Implementation: https://github.com/mozilla/marionett.../marionette.py

Method overview

For a list of all current and future methods and their implementation status, see the JSON protocol, which currently contains a subset of the WebDriver spec, but we will move toward fully supporting the WebDriver spec in time.  The table below summarizes methods which are currently available.

script execution
script_result execute_script(script, script_args=None, special_powers=False)
script_result execute_async_script(script, script_args=None, special_powers=False)
None set_script_timeout(timeout)
context management
str session_capabilities
None set_context(context)
None switch_to_frame(frame_reference)
None switch_to_window(window_reference)
str current_window_handle
list window_handles
None close()
navigation
None navigate(url)
str get_url()
None go_back()
None go_forward()
None refresh()
str absolute_url()
DOM elements
None set_search_timeout(timeout)
HTMLElement find_element(method, target)
list find_elements(method, target)
HTMLElement get_attribute(attribute)
HTMLElement text
HTMLElement send_keys(string)
HTMLElement clear()
HTMLElement click()
HTMLElement is_selected()
HTMLElement is_enabled()
HTMLElement is_displayed()
HTMLElement single_tap(x,y)
HTMLElement double_tap(x,y)
HTMLElement press(x,y)
HTMLElement release(touch_id,x,y)
HTMLElement cancel_touch(touch_id)
str tag_name
dict size
dict location
Action Chain Methods
action_object press(element, x=None, y=None)
action_object release()
action_object move(element)
action_object move_by_offset(x,y)
action_object wait(time=None)
action_object cancel()
action_object perform()
Action Chain Methods
multiaction_object add(action)
multiaction_object perform()
Debugging
None log(msg, level)
list get_logs()
list page_source()

Attributes

Attribute Type Description
emulator Emulator When tests are being run on a b2g emulator, an instance of Marionette's Emulator class, which allows interaction with an emulator under test; otherwise None.
CONTEXT_CHROME str A constant for the "chrome" context, used in set_context().
CONTEXT_CONTENT str A constant for the "content" context, used in set_context().

Script Execution Methods

execute_script(script, script_args=None, special_powers=False)

Executes a synchronous JavaScript script, and returns the result.  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.

For example:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        result = self.marionette.execute_script("return 1;")
        self.assertEqual(result, 1, "invalid execute_script result")

Scripts wishing to access non-standard properties of the window object must use window.wrappedJSObject.  For example:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        result = self.marionette.execute_script("""
          window.wrappedJSObject.test1 = 'foo';
          window.wrappedJSObject.test2 = 'bar';
          return window.wrappedJSObject.test1 + window.wrappedJSObject.test2;
        """)
        self.assertEqual(result, 'foobar', "invalid execute_script result")

Global variables set by individual scripts do not persist between script calls.  If you wish to persist data between script calls, you should use properties of the window object.  For example:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        self.marionette.execute_script("window.wrappedJSObject.test1 = 'foo';")
        result = self.marionette.execute_script("return window.wrappedJSObject.test1;")
        self.assertEqual(result, 'foo', "invalid execute_script result")
Parameters

script - a string containing the JavaScript to execute

script_args - a list of arguments to pass to the script.  Arguments are available to the script using the arguments object.  For example:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        result = self.marionette.execute_script("return arguments[0] + arguments[1];", script_args=[2, 3])
        self.assertEqual(result, 5, "invalid execute_script result")
        some_element = self.marionette.find_element("id", "someElement")
        sid = self.marionette.execute_script("return arguments[0].id;", script_args=[some_element])
        self.assertEqual(some_element.get_attribute("id"), sid)

special_powers - whether or not you want access to https://developer.mozilla.org/en-US/docs/SpecialPowers in your script. Set to False by default because it shouldn't really be used, since you already have access to chrome-level commands if you set context to chrome and do an execute_script. This method was added only to help us run existing Mochitests.

Return value

The return value of the script, or None if the script does not return a value.

execute_async_script(script, script_args=None, special_powers=False)

Executes an asynchronous JavaScript script, and returns the result.  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.  Asynchronous scripts return a value by calling the marionetteScriptFinished() function within the script, or will throw a ScriptTimeoutException if the timeout period, set by set_script_timeout(), is exceeded or not set.  For example:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        self.marionette.set_script_timeout(10000); #set timeout period of 10 seconds
        result = self.marionette.execute_async_script("""
          // this script waits 5 seconds, and then returns the number 1
          setTimeout(function() {
            marionetteScriptFinished(1);
          }, 5000);
        """)
        self.assertEqual(result, 1, "invalid execute_async_script result")

The same limitations regarding global variables and accessing the window object as described for execute_script() apply to execute_async_script() as well.

Parameters

script - a string containing the JavaScript to execute

script_args - a list of arguments to pass to the script.  Arguments are available to the script using the arguments object. See execute_script() for an example.

special_powers - whether or not you want access to https://developer.mozilla.org/en-US/docs/SpecialPowers in your script. Set to False by default because it shouldn't really be used, since you already have access to chrome-level commands if you set context to chrome and do an execute_script. This method was added only to help us run existing Mochitests.

Return value

The return value of the script, or None if the script does not return a value.

import_script(file)

Imports this script into the scope of the execute_script and execute_async_script calls. This is particularly useful if you wish to import your own libraries.

Say you have a script, importfunc.js, that contains:

let testFunc = function() { return "i'm a test function!";};

You can now import this script and use it in an execute call. For example, assuming importfunc.js is in the same directory as the test:

import os
from marionette_test import MarionetteTestCase

class TestImportScript(MarionetteTestCase):
    def test_import_script(self):
        js = os.path.abspath(os.path.join(__file__, os.path.pardir, "importfunc.js"))
        self.marionette.import_script(js)
        self.assertEqual("i'm a test function!", self.marionette.execute_script("return testFunc();"))

Imported scripts persist for the duration of the client's session.

Parameters

file - local file to upload to the marionette server

Return value

None

set_script_timeout(timeout)

Sets the maximum number of ms that an asynchronous script is allowed to run; if it doesn't return in the specified amount of time, a ScriptTimeoutException is raised.

Parameters

timeout - the maximum number of milliseconds an asynchronous script can run without causing an ScriptTimeoutException to be raised

Return value

None

Context Management Methods

session_capabilities

This returns the current capabilities of the browser as a JSON Blob

Parameters

None

Return value

A JSON string that mentioned

set_context(context)

Sets the context in which all subsequent commands will operate.  The CONTEXT_CONTENT context is active until this method is called for the first time.  The active context impacts subsequent commands in different ways.  For example, execute_script() calls in CONTEXT_CONTENT will not have access to XPCOM objects, but they will in CONTEXT_CHROME.

Parameters

context - one of CONTEXT_CHROME or CONTEXT_CONTENT

Return value

None

switch_to_frame(frame_ref)

Switch the current context to the specified frame.  Subsequent commands will operate in the context of the specified frame, if applicable.  An example relevant to B2G and Gaia:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        self.marionette.set_context(self.marionette.CONTEXT_CHROME)
        # launch the clock app, which causes a new frame to be opened
        self.marionette.execute_script("window.wrappedJSObject.Gaia.AppManager.launch('../clock/clock.html')")
        # 'clock' shouldn't be in the href of the current frame, which is the top-level frame for the main window
        self.assertTrue("clock.html" not in self.marionette.execute_script("return document.location.href;"))
        # switch to the first child frame, which should be the clock app
        self.marionette.switch_to_frame(0)
        # 'clock' *should* now be in the href of the current frame
        self.assertTrue("clock.html" in self.marionette.execute_script("return document.location.href;"))        
Parameters

frame_ref - a reference to the frame you want to switch to.  This can be an HTMLElement, an index, name or an id attribute.  If you call switch_to_frame() without an argument, it will switch to the top-level frame.

Return value

None

switch_to_window(window_ref)

Switch to the specified window; subsequent commands will be directed at the new window.

Parameters

window_ref - the id or name of the window to switch to

Return value

None

current_window_handle

Returns a reference to the current window.

Parameters

None

Return value

A reference to the current window.  This reference can be used in later calls to switch_to_window().

window_handles

Returns a list of references to all available browser windows if called in content. If called while in the chrome context, it will list all available windows, not just browser windows (ie: not just 'navigator:browser';).

Parameters

None

Return value

A list of references to all available windows.  These references can be used in later calls to switch_to_window().

close()

This closes the window that is in use by Marionette

Parameters

Window ID of the window you wish to closed

Causes the browser to navigate to the specified url.

Parameters

url - the url to navigate to

Return value

None

get_url()

Returns the url of the active page in the browser.

Parameters

None

Return value

The url of the active page in the browser.

go_back()

Causes the browser to perform a back navigation.

Parameters

None

Return value

None

go_forward()

Causes the browser to perform a forward navigation.

Parameters

None

Return value

None

refresh()

Causes the browser to perform to refresh the current page.

Parameters

None

Return value

None

absolute_url(url)

Marionette includes a webserver which can be used to serve static files located in Marionette's www directory.  This method will return an absolute url for such files.

Parameters

url - the url of a static file, relative to Marionette's www directory.

Return value

The absolute url for the file, which can be used, for example, in calls to navigate().

 

DOM Element Methods

 

set_search_timeout(timeout)

When searching for an element using either of the find_ methods, 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.

After this period of time, if the element is not found, a NoSuchElementException will be raised.

Parameters

timeout - the max number of ms to search for elements using the find_ methods before raising a NoSuchElementException.

Return value

None

find_element(method, target)

Returns an HTMLElement instance for the specified element 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 set_search_timeout().

Parameters

method - the method to use to locate the element; one of: "id", "name", "class name", "tag name", "css selector", "link text", "partial link text" and "xpath". Note that the methods supported in the chrome dom are only "id", "class name", "tag name" and "xpath".

target - the target of the search.  For example, if method = "tag", target might equal "div".  If method = "id", target would be an element id.

Return value

An HTMLElement instance corresponding to the specified criteria.  If multiple elements match the given criteria, only the first is returned.  If no element matches, a NoSuchElementException will be raised.

find_elements(method, target)

Returns a list of all 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 set_search_timeout().

Parameters

method - the method to use to locate the element; one of: "id", "name", "class name", "tag name", "css selector", "link text", "partial link text" and "xpath". Note that the methods supported in the chrome dom are only "id", "class name", "tag name" and "xpath".

target - the target of the search.  For example, if method = "tag", target might equal "div".  If method = "id", target would be an element id.

Return value

A list of HTMLElement instances corresponding to the specified criteria. If no element matches, a NoSuchElementException will be raised.

get_attribute(attribute)

Returns the requested attribute.

Parameters

attribute - the name of the attribute.

Return value

The attribute, or None if no value is set.

text

Returns the visible text of the element, and its child elements.

Parameters

None

Return value

The visible text, with the text of its child elements separated by newlines.

send_keys(String)

Sends the string via synthesized keypresses to the element.

Parameters

string - the string to be sent to the element.

Return value

None

clear()

Clear the input of the element.

Parameters

None

Return value

None

click()

Click the element.

Parameters

None

Return value

None

is_selected()

Check if the element is selected.

Parameters

None

Return value

Returns true if the element is selected, false otherwise.

is_enabled()

Check if the element is enabled.

Parameters

None

Return value

Returns true if the element is enabled, false otherwise.

is_displayed()

Check if the element is displayed.

Parameters

None

Return value

Returns true if the element is displayed, false otherwise.

tag_name

Get the tag name of the element

Parameters

None

Return value

Returns a string of what the element tag name is.

size

Get the size of the element

Parameters

None

Return value

Returns a dictionary with the height and width of the element

location

Get the location of the element

Parameters

None

Return value

Returns a dictionary with the x and y location of an element

single_tap(x, y)

Sends 'touchstart' and 'touchend' events to this element. If no coordinates are given, it will be targetted at the center of the element. If given, it will be targetted at the (x,y) coordinates relative to the top-left corner of the element.

NOTE: Depending on your test environment environment (like in Gaia), you may need to send a chain of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a tap to work, so single_tap() on its own will not be enough.

Parameters

x - optional, x-coordinate to tap, relative to the top-left corner of the element

y - optional, y-coordinate to tap, relative to the top-left corner of the element

Return value

None

double_tap(x, y)

Sends two chains of 'touchstart' and 'touchend' events to this element. If no coordinates are given, it will be targetted at the center of the element. If given, it will be targetted at the (x,y) coordinates relative to the top-left corner of the element.

NOTE: Depending on your test environment environment (like in Gaia), you may need to send two chains of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a double tap to work, so double_tap() on its own will not be enough.

Parameters

x - optional, x-coordinate to tap, relative to the top-left corner of the element

y - optional, y-coordinate to tap, relative to the top-left corner of the element

Return value

None

press(x, y)

Sends a 'touchstart' event to this element. If no coordinates are given, it will be targetted at the center of the element. If given, it will be targetted at the (x,y) coordinates relative to the top-left corner of the element.

NOTE: Depending on your test environment environment (like in Gaia), you may need to send two chains of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a double tap to work, so double_tap() on its own will not be enough.

Parameters

x - optional, x-coordinate to tap, relative to the top-left corner of the element

y - optional, y-coordinate to tap, relative to the top-left corner of the element

Return value

A number which represents the ID of the touch.

release(touch_id, x, y)

Release() can only be called if press() has already be called on this element.

If (x,y) are passed in, then this sends a 'touchmove' event to (x,y) relative to the top-left corner of the element followed by a 'touchend' at the same location. If (x,y) are not passed in, then this just sends a 'touchend' event to this element, to the same location used in the preceeding press() command.

NOTE: Depending on your test environment environment (like in Gaia), you may need to send two chains of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a double tap to work, so double_tap() on its own will not be enough.

Parameters

touch_id - the number returned by press()

x - optional, x-coordinate to tap, relative to the top-left corner of the element

y - optional, y-coordinate to tap, relative to the top-left corner of the element

Return value

None

cancel_touch(touch_id)

Sends a 'touchcancel' event to this element. It can only be called if press() has already be called.

Parameters

touch_id - the number returned by press()

Return value

None

Action Chain Methods

"Action chain" will be used to denote a set of actions that have to be executed in particular order, and will allow simultaneous execution of parallel chains so we can have 'multifinger' gestures. A general example of an action chain is:

class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # find element1 and element2
        element1 = self.marionette.find_element("id", "element1")
        element2 = self.marionette.find_element("id", "element2")
        # create action object
        action = Actions(marionette)
        # add actions (press, wait, move, release) into the object
        action.press(element1).wait(5). move(element2).release()
        # fire all the added events
        action.perform()

This action chain will do a press() on element1, then wait 5 seconds, then move to element2, then, release on element2.

NOTE1: It will execute only when perform() is called. Perform() makes the built action chain being sent to the server side for execution.

NOTE2: Action chain can be performed in segments. An example of element2 displays only after element1 makes use of this.

class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # create an object
        action = Actions(marionette)
        # find element1    
        element1 = self.marionette.find_element("id", element1")
        # press on element1
        action.press(element1).perform()
        # now find element2    
        element2 = self.marionette.find_element("id", element2")
        # same action object which move finger from element1 to element2, and then release at element2    
        action.move(element2).release().perform()

NOTE3: Each finger has 1:1 mapping with a Actions object. If we want multiple fingers on the screen at the same time, refer to MultiAction methods.

NOTE4: If the action chain performs a long press, contextmenu event will be fired.

press(element, x=None, y=None)

Sends a 'touchstart' event to this element. If no coordinates are given, it will be targeted at the center of the element. If given, it will be targeted at the (x,y) coordinates relative to the top-left corner of the element.

Parameters

element - the element to press on

x - optional, x-coordinate to tap, relative to the top-left corner of the element

y - optional, y-coordinate to tap, relative to the top-left corner of the element

Return value

Returns the object itself

release()

release() can only be called if press() has already be called on this element.

release() send 'touchend' event to whenever the finger is

Parameters

None

Return value

Returns the object itself

move(element)

move() can only be called if press() has already be called on this element.

move(element) send 'touchmove' event which moves the finger to target element

Parameters

element - the target element of the move gesture

Return value

Returns the object itself

move_by_offset(x, y)

move_by_offset() can only be called if press() has already be called on this element.

move_by_offset(x, y) send 'touchmove' event

Parameters

x - x-coordinate relative to the top-left corner of the target element of the last touch

y - y-coordinate relative to the top-left corner of the target element of the last touch

Return value

Returns the object itself

wait(time=None)

wait(time) wait for specified time period

Parameters

time - wait for "time" seconds

Return value

Returns the object itself

cancel()

cancel() can only be called if press() has already be called on this element.

cancel() send 'touchcancel' event to whenever the finger is

Parameters

None

Return value

Returns the object itself

perform()

perform() will send the whole action chain built so far to the server side for execution.

Parameters

None

Return value

Returns the object itself

Action Chain Methods

"Action chain" will be used to denote a set of actions that have to be executed in particular order, and will allow simultaneous execution of parallel chains so we can have 'multifinger' gestures. A general example of an action chain is:

class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # find element1 and element2
        element1 = self.marionette.find_element("id", "element1")
        element2 = self.marionette.find_element("id", "element2")
        # create action object
        action = Actions(marionette)
        # add actions (press, wait, move, release) into the object
        action.press(element1).wait(5). move(element2).release()
        # fire all the added events
        action.perform()

This action chain will do a press() on element1, then wait 5 seconds, then move to element2, then, release on element2.

NOTE1: It will execute only when perform() is called. Perform() makes the built action chain being sent to the server side for execution.

NOTE2: Action chain can be performed in segments. An example of element2 displays only after element1 makes use of this.

class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # create an object
        action = Actions(marionette)
        # find element1    
        element1 = self.marionette.find_element("id", element1")
        # press on element1
        action.press(element1).perform()
        # now find element2    
        element2 = self.marionette.find_element("id", element2")
        # same action object which move finger from element1 to element2, and then release at element2    
        action.move(element2).release().perform()

NOTE3: Each finger has 1:1 mapping with a Actions object. If we want multiple fingers on the screen at the same time, refer to MultiAction methods.

NOTE4: If the action chain performs a long press, contextmenu event will be fired.

add(action)

This method adds the action chain specified to the multiaction object.

Parameters

action - one action object

Return value

Returns the object itself

perform()

perform() will send multiple action chains that have been added so far to the server side for execution.

Parameters

None

Return value

None

Debugging

log(msg, level)

You can log messages with this method

 

Parameters

 

msg - The log message

level - A custom log level. If not set, it defaults to "INFO"

Return value

None

get_logs()

Get all logs you made with the log method.

Parameters

None

Return value

List of log message strings

page_source()

Serialises the DOM into a string that can then be worked against.

Parameters

None

Return value

A string representation of the document object

Performance

add_perf_data(suite, name, value)

Add a (name, value) datapoint to a test suite.

Parameters

suite - Name of the testsuite this datapoint will get rolled into

name - Name of the current test

value - some numeric value for the test

Return value

None

Example
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        #add data to testsuite
        self.marionette.add_perf_data("mySuite", "myTest", 50)
        #add more data to the same test in the same suite
        self.marionette.add_perf_data("mySuite", "myTest", 83)
        #add a new test datapoint to the test suite
        self.marionette.add_perf_data("mySuite", "myOtherTest", 900)
        #add data to a new testsuite
        self.marionette.add_perf_data("mySecondSuite", "whooTesting", 89)
Parameters

get_perf_data()

Get all test data from the test in a dict.

Parameters

None

Return value

Dict of testsuite to datapoints. A clear example is below.


Example

Using the same code as the add_perf_data example above:

class TestSomething(MarionetteTestCase):

    def test_foo(self):
        #add data to testsuite
        self.marionette.add_perf_data("mySuite", "myTest", 50)
        #add more data to the same test in the same suite
        self.marionette.add_perf_data("mySuite", "myTest", 83)
        #add a new test datapoint to the test suite
        self.marionette.add_perf_data("mySuite", "myOtherTest", 900)
        #add data to a new testsuite
        self.marionette.add_perf_data("mySecondSuite", "whooTesting", 89)
        
        #retrieve this data:
        print self.marionette.get_perf_data()
        
        """
        
        you should see: 
        
        {u'mySecondSuite': 
                          {u'whooTesting': [89]}, 
         u'mySuite': 
                    {u'myTest': [50, 83],
                     u'myOtherTest': [900]}
        }
         
        """

Revision Source

<p>Every Python test for Marionette has an instance of the <code>Marionette </code>class bound to <code>self.marionette</code>.&nbsp; This instance contains most of the methods used to interact with gecko.</p>
<p>Implementation: <a class="link-https" href="https://github.com/mozilla/marionette_client/blob/master/marionette/marionette.py" rel="freelink">https://github.com/mozilla/marionett.../marionette.py</a></p>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<p>For a list of all current and future methods and their implementation status, see <a class="link-https" href="https://wiki.mozilla.org/Auto-tools/Projects/Marionette/JSON_Protocol" title="https://wiki.mozilla.org/Auto-tools/Projects/Marionette/JSON_Protocol">the JSON protocol</a>, which currently contains a subset of the <a class="external" href="http://www.w3.org/TR/webdriver/" title="http://code.google.com/p/selenium/wiki/JsonWireProtocol">WebDriver spec</a>, but we will move toward fully supporting the WebDriver spec in time.&nbsp; The table below summarizes methods which are currently available.</p>
<table class="standard-table" height="920" width="527">
  <tbody>
    <tr>
      <th>script execution</th>
    </tr>
    <tr>
      <td><code>script_result <a href="/en/Marionette/Marionette#execute_script()" title="en/Marionette/Marionette#execute_script()">execute_script</a>(script, script_args=None, special_powers=False)</code></td>
    </tr>
    <tr>
      <td><code>script_result <a href="/en/Marionette/Marionette#execute_async_script()" title="en/Marionette/Marionette#execute_async_script()">execute_async_script</a>(script, script_args=None, special_powers=False)</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#set_script_timeout()" title="en/Marionette/Marionette#set_script_timeout()">set_script_timeout</a>(timeout)</code></td>
    </tr>
    <tr>
      <th>context management</th>
    </tr>
    <tr>
      <td><code>str session_capabilities</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#set_context()" title="en/Marionette/Marionette#set_context()">set_context</a>(context)</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#switch_to_frame()" title="en/Marionette/Marionette#switch_to_frame()">switch_to_frame</a>(frame_reference)</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#switch_to_window()" title="en/Marionette/Marionette#switch_to_window()">switch_to_window</a>(window_reference)</code></td>
    </tr>
    <tr>
      <td><code>str <a href="#current_window_handle" title="en/Marionette/Marionette#get_window()">current_window_handle</a></code></td>
    </tr>
    <tr>
      <td><code>list <a href="#window_handles" title="en/Marionette/Marionette#get_windows()">window_handles</a></code></td>
    </tr>
    <tr>
      <td><code>None <a href="#close()" title="en/Marionette/Marionette#get_windows()">close</a>()</code></td>
    </tr>
    <tr>
      <th>navigation</th>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#navigate()" title="en/Marionette/Marionette#navigate()">navigate</a>(url)</code></td>
    </tr>
    <tr>
      <td><code>str <a href="/en/Marionette/Marionette#get_url()" title="en/Marionette/Marionette#get_url()">get_url</a>()</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#go_back()" title="en/Marionette/Marionette#go_back()">go_back</a>()</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#go_forward()" title="en/Marionette/Marionette#go_forward()">go_forward</a>()</code></td>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#refresh()" title="en/Marionette/Marionette#refresh()">refresh</a>()</code></td>
    </tr>
    <tr>
      <td><code>str <a href="/en/Marionette/Marionette#absolute_url()" title="en/Marionette/Marionette#absolute_url()">absolute_url</a>()</code></td>
    </tr>
    <tr>
      <th>DOM elements</th>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#set_search_timeout()" title="en/Marionette/Marionette#set_search_timeout()">set_search_timeout</a>(timeout)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#find_element()" title="en/Marionette/Marionette#find_element()">find_element</a>(method, target)</code></td>
    </tr>
    <tr>
      <td><code>list <a href="/en/Marionette/Marionette#find_elements()" title="en/Marionette/Marionette#find_elements()">find_elements</a>(method, target)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#get_attribute()" title="en/Marionette/Marionette#get_attribute()">get_attribute</a>(attribute)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="#text" title="en/Marionette/Marionette#text()">text</a></code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#send_keys()" title="en/Marionette/Marionette#send_keys()">send_keys</a>(string)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#clear()" title="en/Marionette/Marionette#clear()">clear</a>()</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#click()" title="en/Marionette/Marionette#click()">click</a>()</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#is_selected()" title="en/Marionette/Marionette#selected()">is_selected</a>()</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#is_enabled()" title="en/Marionette/Marionette#enabled()">is_enabled</a>()</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#is_displayed()" title="en/Marionette/Marionette#displayed()">is_displayed</a>()</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#single_tap(x,y)" title="/en/Marionette/Marionette#single_tap(x,y)">single_tap</a>(x,y)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#double_tap(x,y)" title="/en/Marionette/Marionette#single_tap(x,y)">double_tap</a>(x,y)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#press(x,y)" title="/en/Marionette/Marionette#single_tap(x,y)">press</a>(x,y)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#release(touch_id,x,y)" title="/en/Marionette/Marionette#single_tap(x,y)">release</a>(touch_id,x,y)</code></td>
    </tr>
    <tr>
      <td><code>HTMLElement <a href="/en/Marionette/Marionette#cancel_touch(touch_id)" title="/en/Marionette/Marionette#single_tap(x,y)">cancel_touch</a>(touch_id)</code></td>
    </tr>
    <tr>
      <td><code>str <a href="#tag_name" title="#tag_name">tag_name</a></code></td>
    </tr>
    <tr>
      <td><code>dict <a href="#size" title="#size">size</a></code></td>
    </tr>
    <tr>
      <td><code>dict <a href="#location" title="#location">location</a></code></td>
    </tr>
    <tr>
      <th><a href="#action_chain" title="#action_chain">Action Chain Methods</a></th>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#press(element,x,y)" title="en/Marionette/Marionette#press(element,x,y)">press</a>(element, x=None, y=None)</code></td>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#release()" title="en/Marionette/Marionette#release()">release</a>()</code></td>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#move(element)" title="en/Marionette/Marionette#move(element)">move</a>(element)</code></td>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#move_by_offset(x,y)" title="en/Marionette/Marionette#move_by_offset(x,y)">move_by_offset</a>(x,y)</code></td>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#wait(time)" title="en/Marionette/Marionette#wait(time)">wait</a>(time=None)</code></td>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#cancel()" title="en/Marionette/Marionette#cancel()">cancel</a>()</code></td>
    </tr>
    <tr>
      <td><code>action_object <a href="/en/Marionette/Marionette#perform()" title="en/Marionette/Marionette#perform()">perform</a>()</code></td>
    </tr>
    <tr>
    <tr>
      <th><a href="#multi_action" title="#multi_action">Action Chain Methods</a></th>
    </tr>
    <tr>
      <td><code>multiaction_object <a href="/en/Marionette/Marionette#add(action)" title="en/Marionette/Marionette#add(action)">add</a>(action)</code></td>
    </tr>
    <tr>
      <td><code>multiaction_object <a href="/en/Marionette/Marionette#multi_perform()" title="en/Marionette/Marionette#multi_perform()">perform</a>()</code></td>
    </tr>
      <th>Debugging</th>
    </tr>
    <tr>
      <td><code>None <a href="/en/Marionette/Marionette#log()" title="en/Marionette/Marionette#log()">log</a>(msg, level)</code></td>
    </tr>
    <tr>
      <td><code>list<a href="/en/Marionette/Marionette#get_logs()" title="en/Marionette/Marionette#get_logs()"> get_logs</a>()</code></td>
    </tr>
    <tr>
      <td><code>list<a href="/en/Marionette/Marionette#page_source()" title="en/Marionette/Marionette#page_source()"> page_source</a>()</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Attributes" name="Attributes">Attributes</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">Attribute</td>
      <td class="header">Type</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code>emulator</code></td>
      <td><a href="/en/Marionette/Emulator" title="en/Marionette/Emulator"><code>Emulator</code></a></td>
      <td>When tests are being run on a b2g emulator, an instance of Marionette's <a href="/en/Marionette/Emulator" title="en/Marionette/Emulator"><code>Emulator </code></a>class, which allows interaction with an emulator under test; otherwise <code>None</code>.</td>
    </tr>
    <tr>
      <td><code>CONTEXT_CHROME</code></td>
      <td><code>str</code></td>
      <td>A constant for the "chrome" context, used in <code>set_context()</code>.</td>
    </tr>
    <tr>
      <td><code>CONTEXT_CONTENT</code></td>
      <td><code>str</code></td>
      <td>A constant for the "content" context, used in <code>set_context()</code>.</td>
    </tr>
  </tbody>
</table>
<h2 id="Script_Execution_Methods">Script Execution Methods</h2>
<h3 id="execute_script()" name="execute_script()">execute_script(script, script_args=None, special_powers=False)</h3>
<p>Executes a synchronous JavaScript script, and returns the result.&nbsp; The script is executed in the context set by the most recent <code>set_context()</code> call, or to the <code>CONTEXT_CONTENT</code> context if <code>set_context()</code> has not been called.</p>
<p>For example:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        result = self.marionette.execute_script("return 1;")
        self.assertEqual(result, 1, "invalid execute_script result")
</pre>
<p>Scripts wishing to access non-standard properties of the <code>window </code>object must use <code>window.wrappedJSObject</code>.&nbsp; For example:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        result = self.marionette.execute_script("""
        &nbsp; window.wrappedJSObject.test1 = 'foo';
        &nbsp; window.wrappedJSObject.test2 = 'bar';
        &nbsp; return window.wrappedJSObject.test1 + window.wrappedJSObject.test2;
        """)
        self.assertEqual(result, 'foobar', "invalid execute_script result")
</pre>
<p>Global variables set by individual scripts do not persist between script calls.&nbsp; If you wish to persist data between script calls, you should use properties of the <code>window </code>object.&nbsp; For example:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        self.marionette.execute_script("window.wrappedJSObject.test1 = 'foo';")
        result = self.marionette.execute_script("return window.wrappedJSObject.test1;")
        self.assertEqual(result, 'foo', "invalid execute_script result")
</pre>
<h5 id="Parameters">Parameters</h5>
<p><strong>script </strong>- a string containing the JavaScript to execute</p>
<p><strong>script_args</strong> - a list of arguments to pass to the script.&nbsp; Arguments are available to the script using the <a href="/en/JavaScript/Reference/Functions_and_function_scope/arguments" title="en/JavaScript/Reference/Functions_and_function_scope/arguments"><code>arguments</code></a> object.&nbsp; For example:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        result = self.marionette.execute_script("return arguments[0] + arguments[1];", script_args=[2, 3])
        self.assertEqual(result, 5, "invalid execute_script result")
        some_element = self.marionette.find_element("id", "someElement")
        sid = self.marionette.execute_script("return arguments[0].id;", script_args=[some_element])
        self.assertEqual(some_element.get_attribute("id"), sid)</pre>
<p><strong>special_powers </strong>- whether or not you want access to https://developer.mozilla.org/en-US/docs/SpecialPowers in your script. Set to False by default because it shouldn't really be used, since you already have access to chrome-level commands if you set context to chrome and do an execute_script. This method was added only to help us run existing Mochitests.</p>
<h5 id="Return_value">Return value</h5>
<p>The return value of the script, or <code>None </code>if the script does not return a value.</p>
<h3 id="execute_async_script()" name="execute_async_script()">execute_async_script(script, script_args=None, special_powers=False)</h3>
<p>Executes an asynchronous JavaScript script, and returns the result.&nbsp; The script is executed in the context set by the most recent <code>set_context()</code> call, or to the <code>CONTEXT_CONTENT</code> context if <code>set_context()</code> has not been called.&nbsp; Asynchronous scripts return a value by calling the <code>marionetteScriptFinished()</code> function within the script, or will throw a <code>ScriptTimeoutException</code> if the timeout period, set by <code>set_script_timeout()</code>, is exceeded or not set.&nbsp; For example:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        self.marionette.<code>set_script_timeout</code>(10000); #set timeout period of 10 seconds
        result = self.marionette.execute_async_script("""
          // this script waits 5 seconds, and then returns the number 1
        &nbsp; setTimeout(function() {
        &nbsp; &nbsp; marionetteScriptFinished(1);
        &nbsp; }, 5000);
        """)
        self.assertEqual(result, 1, "invalid execute_async_script result")
</pre>
<p>The same limitations regarding global variables and accessing the <code>window </code>object as described for <code>execute_script()</code> apply to <code>execute_async_script()</code> as well.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>script </strong>- a string containing the JavaScript to execute</p>
<p><strong>script_args</strong> - a list of arguments to pass to the script.&nbsp; Arguments are available to the script using the <a href="../JavaScript/Reference/Functions_and_function_scope/arguments" rel="internal" title="en/JavaScript/Reference/Functions_and_function_scope/arguments"><code>arguments</code></a> object. See <a href="/en/Marionette/Marionette#execute_script()" title="en/Marionette/Marionette#execute_script()">execute_script()</a> for an example.</p>
<p><strong>special_powers </strong>- whether or not you want access to https://developer.mozilla.org/en-US/docs/SpecialPowers in your script. Set to False by default because it shouldn't really be used, since you already have access to chrome-level commands if you set context to chrome and do an execute_script. This method was added only to help us run existing Mochitests.</p>
<h5 id="Return_value">Return value</h5>
<p>The return value of the script, or <code>None </code>if the script does not return a value.</p>
<h3 id="set_script_timeout()" name="set_script_timeout()">import_script(file)</h3>
<p>Imports this script into the scope of the execute_script and execute_async_script calls. This is particularly useful if you wish to import your own libraries.</p>
<p>Say you have a script, importfunc.js, that contains:</p>
<pre class="brush: js">
let testFunc = function() { return "i'm a test function!";};
</pre>
<p>You can now import this script and use it in an execute call. For example, assuming importfunc.js is in the same directory as the test:</p>
<pre class="brush: python">
import os
from marionette_test import MarionetteTestCase

class TestImportScript(MarionetteTestCase):
    def test_import_script(self):
        js = os.path.abspath(os.path.join(__file__, os.path.pardir, "importfunc.js"))
        self.marionette.import_script(js)
        self.assertEqual("i'm a test function!", self.marionette.execute_script("return testFunc();"))
</pre>
<p>Imported scripts persist for the duration of the client's session.</p>
<h5 id="Parameters">Parameters</h5>
<p>file - local file to upload to the marionette server</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="set_script_timeout()" name="set_script_timeout()">set_script_timeout(timeout)</h3>
<p>Sets the maximum number of ms that an asynchronous script is allowed to run; if it doesn't return in the specified amount of time, a <code>ScriptTimeoutException </code>is raised.</p>
<h5 id="Parameters">Parameters</h5>
<p>timeout - the maximum number of milliseconds an asynchronous script can run without causing an <code>ScriptTimeoutException </code>to be raised</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h2 id="Context_Management_Methods">Context Management Methods</h2>
<h3 id="set_context()" name="set_context()"><a name="session_capabilities">session_capabilities</a></h3>
<p>This returns the current capabilities of the browser as a JSON Blob</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>A JSON string that mentioned</p>
<h3 id="set_context()" name="set_context()">set_context(context)</h3>
<p>Sets the context in which all subsequent commands will operate.&nbsp; The <code>CONTEXT_CONTENT</code> context is active until this method is called for the first time.&nbsp; The active context impacts subsequent commands in different ways.&nbsp; For example, <code>execute_script()</code> calls in CONTEXT_CONTENT will not have access to XPCOM objects, but they will in <code>CONTEXT_CHROME</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>context </strong>- one of <code>CONTEXT_CHROME</code> or <code>CONTEXT_CONTENT</code></p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="switch_to_frame()" name="switch_to_frame()">switch_to_frame(frame_ref)</h3>
<p>Switch the current context to the specified frame.&nbsp; Subsequent commands will operate in the context of the specified frame, if applicable.&nbsp; An example relevant to B2G and Gaia:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        self.marionette.set_context(self.marionette.CONTEXT_CHROME)
        # launch the clock app, which causes a new frame to be opened
        self.marionette.execute_script("window.wrappedJSObject.Gaia.AppManager.launch('../clock/clock.html')")
        # 'clock' shouldn't be in the href of the current frame, which is the top-level frame for the main window
        self.assertTrue("clock.html" not in self.marionette.execute_script("return document.location.href;"))
        # switch to the first child frame, which should be the clock app
        self.marionette.switch_to_frame(0)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # 'clock' *should* now be in the href of the current frame
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.assertTrue("clock.html" in self.marionette.execute_script("return document.location.href;"))        
</pre>
<h5 id="Parameters">Parameters</h5>
<p><strong>frame_ref</strong> - a reference to the frame you want to switch to.&nbsp; This can be an <code>HTMLElement</code>, an index, name or an id attribute.&nbsp; If you call <code>switch_to_frame()</code> without an argument, it will switch to the top-level frame.</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="switch_to_window()" name="switch_to_window()">switch_to_window(window_ref)</h3>
<p>Switch to the specified window; subsequent commands will be directed at the new window.</p>
<h5 id="Parameters">Parameters</h5>
<p>window_ref - the id or name of the window to switch to</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="get_window()" name="get_window()"><a name="current_window_handle">current_window_handle</a></h3>
<p>Returns a reference to the current window.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>A reference to the current window.&nbsp; This reference can be used in later calls to <code>switch_to_window()</code>.</p>
<h3 id="get_windows()" name="get_windows()"><a name="window_handles">window_handles</a></h3>
<p>Returns a list of references to all available browser windows if called in content. If called while in the chrome context, it will list all available windows, not just browser windows (ie: not just 'navigator:browser';).</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>A list of references to all available windows.&nbsp; These references can be used in later calls to <code>switch_to_window()</code>.</p>
<h3 id="close()"><a name="close()">close()</a></h3>
<p>This closes the window that is in use by Marionette</p>
<h5 id="Parameters">Parameters</h5>
<p>Window ID of the window you wish to closed</p>
<h2 id="Navigation_Methods">Navigation Methods</h2>
<h3 id="navigate()" name="navigate()">navigate(url)</h3>
<p>Causes the browser to navigate to the specified url.</p>
<h5 id="Parameters">Parameters</h5>
<p>url - the url to navigate to</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="get_url()" name="get_url()">get_url()</h3>
<p>Returns the url of the active page in the browser.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>The url of the active page in the browser.</p>
<h3 id="go_back()" name="go_back()">go_back()</h3>
<p>Causes the browser to perform a back navigation.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="go_forward()" name="go_forward()">go_forward()</h3>
<p>Causes the browser to perform a forward navigation.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="refresh()" name="refresh()">refresh()</h3>
<p>Causes the browser to perform to refresh the current page.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="absolute_url()" name="absolute_url()">absolute_url(url)</h3>
<p>Marionette includes a webserver which can be used to serve static files located in Marionette's <code>www </code>directory.&nbsp; This method will return an absolute url for such files.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>url </strong>- the url of a static file, relative to Marionette's <code>www </code>directory.</p>
<h5 id="Return_value">Return value</h5>
<p>The absolute url for the file, which can be used, for example, in calls to <code>navigate()</code>.</p>
<p>&nbsp;</p>
<h2 id="DOM_Element_Methods">DOM Element Methods</h2>
<p>&nbsp;</p>
<h3 id="set_search_timeout()" name="set_search_timeout()">set_search_timeout(timeout)</h3>
<p>When searching for an element using either of the <code>find_</code> methods, the method will continue trying to locate the element for up to <code>timeout </code>ms.&nbsp; 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.</p>
<p>After this period of time, if the element is not found, a <code>NoSuchElementException </code>will be raised.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>timeout </strong>- the max number of ms to search for elements using the<code> find_</code> methods before raising a <code>NoSuchElementException</code>.</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="find_element()" name="find_element()">find_element(method, target)</h3>
<p>Returns an <code>HTMLElement </code>instance for the specified element in the current context.&nbsp; An <code>HTMLElement </code>instance may be used to call other methods on the element, such as <code>click()</code>.&nbsp; If no element is immediately found, the attempt to locate an element will be repeated for up to the amount of time set by <code>set_search_timeout()</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>method </strong>- the method to use to locate the element; one of: "id", "name", "class name", "tag name", "css selector", "link text", "partial link text" and "xpath". Note that the methods supported in the chrome dom are only "id", "class name", "tag name" and "xpath".</p>
<p><strong>target </strong>- the target of the search.&nbsp; For example, if <code>method </code>= "tag", <code>target </code>might equal "div".&nbsp; If <code>method </code>= "id", <code>target </code>would be an element id.</p>
<h5 id="Return_value">Return value</h5>
<p>An <code>HTMLElement </code>instance corresponding to the specified criteria.&nbsp; If multiple elements match the given criteria, only the first is returned.&nbsp; If no element matches, a <code>NoSuchElementException </code>will be raised.</p>
<h3 id="find_elements()" name="find_elements()">find_elements(method, target)</h3>
<p>Returns a list of all <code>HTMLElement </code>instances that match the specified method and target in the current context.&nbsp; An <code>HTMLElement </code>instance may be used to call other methods on the element, such as <code>click()</code>.&nbsp; If no element is immediately found, the attempt to locate an element will be repeated for up to the amount of time set by <code>set_search_timeout()</code>.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>method </strong>- the method to use to locate the element; one of: "id", "name", "class name", "tag name", "css selector", "link text", "partial link text" and "xpath". Note that the methods supported in the chrome dom are only "id", "class name", "tag name" and "xpath".</p>
<p><strong>target </strong>- the target of the search.&nbsp; For example, if <code>method </code>= "tag", <code>target </code>might equal "div".&nbsp; If <code>method </code>= "id", <code>target </code>would be an element id.</p>
<h5 id="Return_value">Return value</h5>
<p>A list of <code>HTMLElement </code>instances corresponding to the specified criteria. If no element matches, a <code>NoSuchElementException </code>will be raised.</p>
<h3 id="find_elements()" name="find_elements()">get_attribute(attribute)</h3>
<p>Returns the requested attribute.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>attribute </strong>- the name of the attribute.</p>
<h5 id="Return_value">Return value</h5>
<p>The attribute, or None if no value is set.</p>
<h3 id="find_elements()" name="find_elements()">text</h3>
<p>Returns the visible text of the element, and its child elements.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>The visible text, with the text of its child elements separated by newlines.</p>
<h3 id="find_elements()" name="find_elements()">send_keys(String)</h3>
<p>Sends the string via synthesized keypresses to the element.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>string </strong>- the string to be sent to the element.</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="find_elements()" name="find_elements()">clear()</h3>
<p>Clear the input of the element.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="find_elements()" name="find_elements()">click()</h3>
<p>Click the element.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="find_elements()" name="find_elements()"><a name="is_selected()">is_selected()</a></h3>
<p>Check if the element is selected.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns true if the element is selected, false otherwise.</p>
<h3 id="find_elements()" name="find_elements()"><a name="is_enabled()">is_enabled()</a></h3>
<p>Check if the element is enabled.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns true if the element is enabled, false otherwise.</p>
<h3 id="find_elements()" name="find_elements()"><a name="is_displayed()">is_displayed()</a></h3>
<p>Check if the element is displayed.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns true if the element is displayed, false otherwise.</p>
<h3 id="find_elements()" name="find_elements()"><a name="tag_name">tag_name</a></h3>
<p>Get the tag name of the element</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns a string of what the element tag name is.</p>
<h3 id="find_elements()" name="find_elements()"><a name="size">size</a></h3>
<p>Get the size of the element</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns a dictionary with the height and width of the element</p>
<h3 id="find_elements()" name="find_elements()"><a name="location">location</a></h3>
<p>Get the location of the element</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns a dictionary with the x and y location of an element</p>
<h3 id="single_tap(x,y)" name="single_tap(x,y)"><a name="single_tap(x,y)">single_tap(x, y)</a></h3>
<p>Sends 'touchstart' and 'touchend' events to this element. If no coordinates are given, it will be targetted at the center of the element. If given, it will be targetted at the (x,y) coordinates relative to the top-left corner of the element.</p>
<p><strong>NOTE</strong>: Depending on your test environment environment (like in Gaia), you may need to send a chain of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a tap to work, so single_tap() on its own will not be enough.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>x</strong> - optional, x-coordinate to tap, relative to the top-left corner of the element</p>
<p><strong>y</strong> - optional, y-coordinate to tap, relative to the top-left corner of the element</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="double_tap(x,y)" name="double_tap(x,y)"><a name="double_tap(x,y)">double_tap(x, y)</a></h3>
<p>Sends two chains of 'touchstart' and 'touchend' events to this element. If no coordinates are given, it will be targetted at the center of the element. If given, it will be targetted at the (x,y) coordinates relative to the top-left corner of the element.</p>
<p><strong>NOTE</strong>: Depending on your test environment environment (like in Gaia), you may need to send two chains of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a double tap to work, so double_tap() on its own will not be enough.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>x</strong> - optional, x-coordinate to tap, relative to the top-left corner of the element</p>
<p><strong>y</strong> - optional, y-coordinate to tap, relative to the top-left corner of the element</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="press(x,y)" name="press(x,y)"><a name="press(x,y)">press(x, y)</a></h3>
<p>Sends a 'touchstart' event to this element. If no coordinates are given, it will be targetted at the center of the element. If given, it will be targetted at the (x,y) coordinates relative to the top-left corner of the element.</p>
<p><strong>NOTE</strong>: Depending on your test environment environment (like in Gaia), you may need to send two chains of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a double tap to work, so double_tap() on its own will not be enough.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>x</strong> - optional, x-coordinate to tap, relative to the top-left corner of the element</p>
<p><strong>y</strong> - optional, y-coordinate to tap, relative to the top-left corner of the element</p>
<h5 id="Return_value">Return value</h5>
<p>A number which represents the ID of the touch.</p>
<h3 id="release(touch_id,x,y)" name="release(touch_id,x,y)"><a name="release(touch_id,x,y)">release(touch_id, x, y)</a></h3>
<p>Release() can only be called if press() has already be called on this element.</p>
<p>If (x,y) are passed in, then this sends a 'touchmove' event to (x,y) relative to the top-left corner of the element followed by a 'touchend' at the same location. If (x,y) are not passed in, then this just sends a 'touchend' event to this element, to the same location used in the preceeding press() command.</p>
<p><strong>NOTE</strong>: Depending on your test environment environment (like in Gaia), you may need to send two chains of 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mouseclick' events in order for a double tap to work, so double_tap() on its own will not be enough.</p>
<h5 id="Parameters">Parameters</h5>
<p>touch_id - the number returned by press()</p>
<p><strong>x</strong> - optional, x-coordinate to tap, relative to the top-left corner of the element</p>
<p><strong>y</strong> - optional, y-coordinate to tap, relative to the top-left corner of the element</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="cancel_touch(touch_id)" name="cancel_touch(touch_id)"><a name="cancel_touch(touch_id)">cancel_touch(touch_id)</a></h3>
<p>Sends a 'touchcancel' event to this element. It can only be called if press() has already be called.</p>
<h5 id="Parameters">Parameters</h5>
<p>touch_id - the number returned by press()</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h2 id="Action_Chain_Methods"><a name="action_chain">Action Chain Methods</a></h2>
<p>"Action chain" will be used to denote a set of actions that have to be executed in particular order, and will allow simultaneous execution of parallel chains so we can have 'multifinger' gestures. A general example of an action chain is:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # find element1 and element2
        element1 = self.marionette.find_element("id", "element1")
        element2 = self.marionette.find_element("id", "element2")
        # create action object
        action = Actions(marionette)
        # add actions (press, wait, move, release) into the object
        action.press(element1).wait(5). move(element2).release()
        # fire all the added events
        action.perform()
</pre>
<p>This action chain will do a press() on element1, then wait 5 seconds, then move to element2, then, release on element2.</p>
<p><strong>NOTE1</strong>: It will execute only when perform() is called. Perform() makes the built action chain being sent to the server side for execution.</p>
<p><strong>NOTE2</strong>: Action chain can be performed in segments. An example of element2 displays only after element1 makes use of this.</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # create an object
        action = Actions(marionette)
        # find element1    
        element1 = self.marionette.find_element("id", element1")
        # press on element1
        action.press(element1).perform()
        # now find element2    
        element2 = self.marionette.find_element("id", element2")
        # same action object which move finger from element1 to element2, and then release at element2    
        action.move(element2).release().perform()
</pre>
<p><strong>NOTE3</strong>: Each finger has 1:1 mapping with a Actions object. If we want multiple fingers on the screen at the same time, refer to MultiAction methods.</p>
<p><strong>NOTE4</strong>: If the action chain performs a long press, contextmenu event will be fired.</p>
<h3 id="press(element,x,y)" name="press(element,x,y)"><a name="press(element,x,y)">press(element, x=None, y=None)</a></h3>
<p>Sends a 'touchstart' event to this element. If no coordinates are given, it will be targeted at the center of the element. If given, it will be targeted at the (x,y) coordinates relative to the top-left corner of the element.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>element</strong> - the element to press on</p>
<p><strong>x</strong> - optional, x-coordinate to tap, relative to the top-left corner of the element</p>
<p><strong>y</strong> - optional, y-coordinate to tap, relative to the top-left corner of the element</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="release()" name="release()"><a name="release()">release()</a></h3>
<p>release() can only be called if press() has already be called on this element.</p>
<p>release() send 'touchend' event to whenever the finger is</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="move(element)" name="move(element)"><a name="move(element)">move(element)</a></h3>
<p>move() can only be called if press() has already be called on this element.</p>
<p>move(element) send 'touchmove' event which moves the finger to target element</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>element</strong> - the target element of the move gesture</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="move_by_offset(x,y)" name="move_by_offset(x,y)"><a name="move_by_offset(x,y)">move_by_offset(x, y)</a></h3>
<p>move_by_offset() can only be called if press() has already be called on this element.</p>
<p>move_by_offset(x, y) send 'touchmove' event</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>x</strong> - x-coordinate relative to the top-left corner of the target element of the last touch</p>
<p><strong>y</strong> - y-coordinate relative to the top-left corner of the target element of the last touch</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="wait(time)" name="wait(time)"><a name="wait(time)">wait(time=None)</a></h3>
<p>wait(time) wait for specified time period</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>time</strong> - wait for "time" seconds</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="cancel()" name="cancel()"><a name="cancel()">cancel()</a></h3>
<p>cancel() can only be called if press() has already be called on this element.</p>
<p>cancel() send 'touchcancel' event to whenever the finger is</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="perform()" name="perform()"><a name="perform()">perform()</a></h3>
<p>perform() will send the whole action chain built so far to the server side for execution.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h2 id="Action_Chain_Methods"><a name="action_chain">Action Chain Methods</a></h2>
<p>"Action chain" will be used to denote a set of actions that have to be executed in particular order, and will allow simultaneous execution of parallel chains so we can have 'multifinger' gestures. A general example of an action chain is:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # find element1 and element2
        element1 = self.marionette.find_element("id", "element1")
        element2 = self.marionette.find_element("id", "element2")
        # create action object
        action = Actions(marionette)
        # add actions (press, wait, move, release) into the object
        action.press(element1).wait(5). move(element2).release()
        # fire all the added events
        action.perform()
</pre>
<p>This action chain will do a press() on element1, then wait 5 seconds, then move to element2, then, release on element2.</p>
<p><strong>NOTE1</strong>: It will execute only when perform() is called. Perform() makes the built action chain being sent to the server side for execution.</p>
<p><strong>NOTE2</strong>: Action chain can be performed in segments. An example of element2 displays only after element1 makes use of this.</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):


    def test_foo(self):
        # get html file
        testAction = self.marionette.absolute_url("testFool.html")
        # navigate to the file
        self.marionette.navigate(testAction)
        # create an object
        action = Actions(marionette)
        # find element1    
        element1 = self.marionette.find_element("id", element1")
        # press on element1
        action.press(element1).perform()
        # now find element2    
        element2 = self.marionette.find_element("id", element2")
        # same action object which move finger from element1 to element2, and then release at element2    
        action.move(element2).release().perform()
</pre>
<p><strong>NOTE3</strong>: Each finger has 1:1 mapping with a Actions object. If we want multiple fingers on the screen at the same time, refer to MultiAction methods.</p>
<p><strong>NOTE4</strong>: If the action chain performs a long press, contextmenu event will be fired.</p>
<h3 id="add(action)" name="add(action)"><a name="add(action)">add(action)</a></h3>
<p>This method adds the action chain specified to the multiaction object.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>action</strong> - one action object</p>
<h5 id="Return_value">Return value</h5>
<p>Returns the object itself</p>
<h3 id="multi_perform()" name="multi_perform()"><a name="multi_perform()">perform()</a></h3>
<p>perform() will send multiple action chains that have been added so far to the server side for execution.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h2 id="Debugging">Debugging</h2>
<h3 id="log()" name="log()">log(msg, level)</h3>
<p>You can log messages with this method</p>
<p>&nbsp;</p>
<h5 id="Parameters">Parameters</h5>
<p>&nbsp;</p>
<p><strong>msg </strong>- The log message</p>
<p><strong>level </strong>- A custom log level. If not set, it defaults to "INFO"</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h3 id="get_logs()" name="get_logs()">get_logs()</h3>
<p>Get all logs you made with the <code>log</code> method.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>List of log message strings</p>
<h3 id="page_source()" name="page_source()">page_source()</h3>
<p>Serialises the DOM into a string that can then be worked against.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>A string representation of the document object</p>
<h2 id="Performance">Performance</h2>
<h3 id="log()" name="log()">add_perf_data(suite, name, value)</h3>
<p>Add a (name, value) datapoint to a test suite.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>suite</strong> - Name of the testsuite this datapoint will get rolled into</p>
<p><strong>name</strong> - Name of the current test</p>
<p><strong>value</strong> - some numeric value for the test</p>
<h5 id="Return_value">Return value</h5>
<p>None</p>
<h5 id="Example">Example</h5>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        #add data to testsuite
        self.marionette.add_perf_data("mySuite", "myTest", 50)
        #add more data to the same test in the same suite
        self.marionette.add_perf_data("mySuite", "myTest", 83)
        #add a new test datapoint to the test suite
        self.marionette.add_perf_data("mySuite", "myOtherTest", 900)
        #add data to a new testsuite
        self.marionette.add_perf_data("mySecondSuite", "whooTesting", 89)
</pre>
<h5 id="Parameters">Parameters</h5>
<h3 id="get_logs()" name="get_logs()">get_perf_data()</h3>
<p>Get all test data from the test in a dict.</p>
<h5 id="Parameters">Parameters</h5>
<p>None</p>
<h5 id="Return_value">Return value</h5>
<p>Dict of testsuite to datapoints. A clear example is below.</p>
<h5 id="
__Example"><br />
  Example</h5>
<p>Using the same code as the add_perf_data example above:</p>
<pre class="brush: python">
class TestSomething(MarionetteTestCase):

    def test_foo(self):
        #add data to testsuite
        self.marionette.add_perf_data("mySuite", "myTest", 50)
        #add more data to the same test in the same suite
        self.marionette.add_perf_data("mySuite", "myTest", 83)
        #add a new test datapoint to the test suite
        self.marionette.add_perf_data("mySuite", "myOtherTest", 900)
        #add data to a new testsuite
        self.marionette.add_perf_data("mySecondSuite", "whooTesting", 89)
        
        #retrieve this data:
        print self.marionette.get_perf_data()
        
        """
        
        you should see: 
        
        {u'mySecondSuite': 
                          {u'whooTesting': [89]}, 
         u'mySuite': 
                    {u'myTest': [50, 83],
                     u'myOtherTest': [900]}
        }
         
        """
</pre>
Revert to this revision