mozilla

Compare Revisions

Marionette

Change Revisions

Revision 455081:

Revision 455081 by mdas on

Revision 456459:

Revision 456459 by wlach on

Title:
Marionette
Marionette
Slug:
Marionette/Marionette
Marionette/Marionette
Content:

Revision 455081
Revision 456459
t8      Every Python test for Marionette has an instance of the <cot8      Documentation for the Marionette Python Client has moved to
>de>Marionette</code> class bound to <code>self.marionette</code>.> readthedocs: <a class="link-https" href="https://marionette_clie
>&nbsp; This instance contains most of the methods used to interac>nt.readthedocs.org/en/latest/" rel="freelink">https://marionette_
>t with gecko.>client.readthedocs.org/en/latest/</a>
9    </p>
10    <p>
11      Implementation: <a class="link-https" href="https://github.
>com/mozilla/marionette_client/blob/master/marionette/marionette.p 
>y" rel="freelink">https://github.com/mozilla/marionett.../marione 
>tte.py</a> 
12    </p>
13    <h2 id="Method_overview" name="Method_overview">
14      Method overview
15    </h2>
16    <p>
17      For a list of all current and future methods and their impl
>ementation status, see <a class="link-https" href="https://wiki.m 
>ozilla.org/Auto-tools/Projects/Marionette/JSON_Protocol" title="h 
>ttps://wiki.mozilla.org/Auto-tools/Projects/Marionette/JSON_Proto 
>col">the JSON protocol</a>, which currently contains a subset of  
>the <a class="external" href="http://www.w3.org/TR/webdriver/" ti 
>tle="http://code.google.com/p/selenium/wiki/JsonWireProtocol">Web 
>Driver spec</a>, but we will move toward fully supporting the Web 
>Driver spec in time.&nbsp; The table below summarizes methods whi 
>ch are currently available. 
18    </p>
19    <table class="standard-table" height="920" width="527">
20      <tbody>
21        <tr>
22          <th>
23            script execution
24          </th>
25        </tr>
26        <tr>
27          <td>
28            <code>script_result <a href="/en/Marionette/Marionett
>e#execute_script()" title="en/Marionette/Marionette#execute_scrip 
>t()">execute_script</a>(script, script_args=None, special_powers= 
>False, new_sandbox=True)</code> 
29          </td>
30        </tr>
31        <tr>
32          <td>
33            <code>script_result <a href="/en/Marionette/Marionett
>e#execute_async_script()" title="en/Marionette/Marionette#execute 
>_async_script()">execute_async_script</a>(script, script_args=Non 
>e, special_powers=False, new_sandbox=True)</code> 
34          </td>
35        </tr>
36        <tr>
37          <td>
38            <code>None <a href="/en/Marionette/Marionette#set_scr
>ipt_timeout()" title="en/Marionette/Marionette#set_script_timeout 
>()">set_script_timeout</a>(timeout)</code> 
39          </td>
40        </tr>
41        <tr>
42          <th>
43            context management
44          </th>
45        </tr>
46        <tr>
47          <td>
48            <code>str session_capabilities</code>
49          </td>
50        </tr>
51        <tr>
52          <td>
53            <code>None <a href="/en/Marionette/Marionette#set_con
>text()" title="en/Marionette/Marionette#set_context()">set_contex 
>t</a>(context)</code> 
54          </td>
55        </tr>
56        <tr>
57          <td>
58            <code>None <a href="/en/Marionette/Marionette#switch_
>to_frame()" title="en/Marionette/Marionette#switch_to_frame()">sw 
>itch_to_frame</a>(frame_reference)</code> 
59          </td>
60        </tr>
61        <tr>
62          <td>
63            <code>None <a href="/en/Marionette/Marionette#switch_
>to_window()" title="en/Marionette/Marionette#switch_to_window()"> 
>switch_to_window</a>(window_reference)</code> 
64          </td>
65        </tr>
66        <tr>
67          <td>
68            <code>str <a href="#current_window_handle" title="en/
>Marionette/Marionette#get_window()">current_window_handle</a></co 
>de> 
69          </td>
70        </tr>
71        <tr>
72          <td>
73            <code>list <a href="#window_handles" title="en/Marion
>ette/Marionette#get_windows()">window_handles</a></code> 
74          </td>
75        </tr>
76        <tr>
77          <td>
78            <code>None <a href="#close()" title="en/Marionette/Ma
>rionette#get_windows()">close</a>()</code> 
79          </td>
80        </tr>
81        <tr>
82          <th>
83            navigation
84          </th>
85        </tr>
86        <tr>
87          <td>
88            <code>None <a href="/en/Marionette/Marionette#navigat
>e()" title="en/Marionette/Marionette#navigate()">navigate</a>(url 
>)</code> 
89          </td>
90        </tr>
91        <tr>
92          <td>
93            <code>str <a href="/en/Marionette/Marionette#get_url(
>)" title="en/Marionette/Marionette#get_url()">get_url</a>()</code 
>> 
94          </td>
95        </tr>
96        <tr>
97          <td>
98            <code>None <a href="/en/Marionette/Marionette#go_back
>()" title="en/Marionette/Marionette#go_back()">go_back</a>()</cod 
>e> 
99          </td>
100        </tr>
101        <tr>
102          <td>
103            <code>None <a href="/en/Marionette/Marionette#go_forw
>ard()" title="en/Marionette/Marionette#go_forward()">go_forward</ 
>a>()</code> 
104          </td>
105        </tr>
106        <tr>
107          <td>
108            <code>None <a href="/en/Marionette/Marionette#refresh
>()" title="en/Marionette/Marionette#refresh()">refresh</a>()</cod 
>e> 
109          </td>
110        </tr>
111        <tr>
112          <td>
113            <code>str <a href="/en/Marionette/Marionette#absolute
>_url()" title="en/Marionette/Marionette#absolute_url()">absolute_ 
>url</a>()</code> 
114          </td>
115        </tr>
116        <tr>
117          <th>
118            DOM elements
119          </th>
120        </tr>
121        <tr>
122          <td>
123            <code>None <a href="/en/Marionette/Marionette#set_sea
>rch_timeout()" title="en/Marionette/Marionette#set_search_timeout 
>()">set_search_timeout</a>(timeout)</code> 
124          </td>
125        </tr>
126        <tr>
127          <td>
128            <code>HTMLElement <a href="/en/Marionette/Marionette#
>find_element()" title="en/Marionette/Marionette#find_element()">f 
>ind_element</a>(method, target)</code> 
129          </td>
130        </tr>
131        <tr>
132          <td>
133            <code>list <a href="/en/Marionette/Marionette#find_el
>ements()" title="en/Marionette/Marionette#find_elements()">find_e 
>lements</a>(method, target)</code> 
134          </td>
135        </tr>
136        <tr>
137          <td>
138            <code>HTMLElement <a href="/en/Marionette/Marionette#
>get_attribute()" title="en/Marionette/Marionette#get_attribute()" 
>>get_attribute</a>(attribute)</code> 
139          </td>
140        </tr>
141        <tr>
142          <td>
143            <code>HTMLElement <a href="#text" title="en/Marionett
>e/Marionette#text()">text</a></code> 
144          </td>
145        </tr>
146        <tr>
147          <td>
148            <code>HTMLElement <a href="/en/Marionette/Marionette#
>send_keys()" title="en/Marionette/Marionette#send_keys()">send_ke 
>ys</a>(string)</code> 
149          </td>
150        </tr>
151        <tr>
152          <td>
153            <code>HTMLElement <a href="/en/Marionette/Marionette#
>clear()" title="en/Marionette/Marionette#clear()">clear</a>()</co 
>de> 
154          </td>
155        </tr>
156        <tr>
157          <td>
158            <code>HTMLElement <a href="/en/Marionette/Marionette#
>click()" title="en/Marionette/Marionette#click()">click</a>()</co 
>de> 
159          </td>
160        </tr>
161        <tr>
162          <td>
163            <code>HTMLElement <a href="/en/Marionette/Marionette#
>is_selected()" title="en/Marionette/Marionette#selected()">is_sel 
>ected</a>()</code> 
164          </td>
165        </tr>
166        <tr>
167          <td>
168            <code>HTMLElement <a href="/en/Marionette/Marionette#
>is_enabled()" title="en/Marionette/Marionette#enabled()">is_enabl 
>ed</a>()</code> 
169          </td>
170        </tr>
171        <tr>
172          <td>
173            <code>HTMLElement <a href="/en/Marionette/Marionette#
>is_displayed()" title="en/Marionette/Marionette#displayed()">is_d 
>isplayed</a>()</code> 
174          </td>
175        </tr>
176        <tr>
177          <td>
178            <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> 
179          </td>
180        </tr>
181        <tr>
182          <td>
183            <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> 
184          </td>
185        </tr>
186        <tr>
187          <td>
188            <code>HTMLElement <a href="/en/Marionette/Marionette#
>press(x,y)" title="/en/Marionette/Marionette#single_tap(x,y)">pre 
>ss</a>(x,y)</code> 
189          </td>
190        </tr>
191        <tr>
192          <td>
193            <code>HTMLElement <a href="/en/Marionette/Marionette#
>release(touch_id,x,y)" title="/en/Marionette/Marionette#single_ta 
>p(x,y)">release</a>(touch_id,x,y)</code> 
194          </td>
195        </tr>
196        <tr>
197          <td>
198            <code>HTMLElement <a href="/en/Marionette/Marionette#
>cancel_touch(touch_id)" title="/en/Marionette/Marionette#single_t 
>ap(x,y)">cancel_touch</a>(touch_id)</code> 
199          </td>
200        </tr>
201        <tr>
202          <td>
203            <code>str <a href="#tag_name" title="#tag_name">tag_n
>ame</a></code> 
204          </td>
205        </tr>
206        <tr>
207          <td>
208            <code>dict <a href="#size" title="#size">size</a></co
>de> 
209          </td>
210        </tr>
211        <tr>
212          <td>
213            <code>dict <a href="#location" title="#location">loca
>tion</a></code> 
214          </td>
215        </tr>
216        <tr>
217          <th>
218            <a href="#action_chain" title="#action_chain">Action 
>Chain Methods</a> 
219          </th>
220        </tr>
221        <tr>
222          <td>
223            <code>action_object <a href="/en/Marionette/Marionett
>e#press(element,x,y)" title="en/Marionette/Marionette#press(eleme 
>nt,x,y)">press</a>(element, x=None, y=None)</code> 
224          </td>
225        </tr>
226        <tr>
227          <td>
228            <code>action_object <a href="/en/Marionette/Marionett
>e#release()" title="en/Marionette/Marionette#release()">release</ 
>a>()</code> 
229          </td>
230        </tr>
231        <tr>
232          <td>
233            <code>action_object <a href="/en/Marionette/Marionett
>e#move(element)" title="en/Marionette/Marionette#move(element)">m 
>ove</a>(element)</code> 
234          </td>
235        </tr>
236        <tr>
237          <td>
238            <code>action_object <a href="/en/Marionette/Marionett
>e#move_by_offset(x,y)" title="en/Marionette/Marionette#move_by_of 
>fset(x,y)">move_by_offset</a>(x,y)</code> 
239          </td>
240        </tr>
241        <tr>
242          <td>
243            <code>action_object <a href="/en/Marionette/Marionett
>e#wait(time)" title="en/Marionette/Marionette#wait(time)">wait</a 
>>(time=None)</code> 
244          </td>
245        </tr>
246        <tr>
247          <td>
248            <code>action_object <a href="/en/Marionette/Marionett
>e#cancel()" title="en/Marionette/Marionette#cancel()">cancel</a>( 
>)</code> 
249          </td>
250        </tr>
251        <tr>
252          <td>
253            <code>action_object <a href="/en/Marionette/Marionett
>e#long_press(element,time_in_seconds)" title="en/Marionette/Mario 
>nette#cancel()">long_press</a>(element, time_in_seconds)</code> 
254          </td>
255        </tr>
256        <tr>
257          <td>
258            <code>action_object <a href="/en/Marionette/Marionett
>e#flick(element,x1,y1,x2,y2,duration)" title="en/Marionette/Mario 
>nette#cancel()">flick</a>(element, x1, y1, x2, y2, duration=200</ 
>code><code>)</code> 
259          </td>
260        </tr>
261        <tr>
262          <td>
263            <code>action_object <a href="/en/Marionette/Marionett
>e#tap(element,x,y)" title="en/Marionette/Marionette#cancel()">tap 
></a>(element, x=None, y=None)</code> 
264          </td>
265        </tr>
266        <tr>
267          <td>
268            <code>action_object <a href="/en/Marionette/Marionett
>e#double_tap(element,x,y)" title="en/Marionette/Marionette#cancel 
>()">double_tap</a>(element, x=None, y=None)</code> 
269          </td>
270        </tr>
271        <tr>
272          <td>
273            <code>action_object <a href="/en/Marionette/Marionett
>e#perform()" title="en/Marionette/Marionette#perform()">perform</ 
>a>()</code> 
274          </td>
275        </tr>
276        <tr>
277          <td></td>
278        </tr>
279        <tr>
280          <th>
281            <a href="#multi_action" title="#multi_action">Multiac
>tion Methods</a> 
282          </th>
283        </tr>
284        <tr>
285          <td>
286            <code>multiaction_object <a href="/en/Marionette/Mari
>onette#add(action)" title="en/Marionette/Marionette#add(action)"> 
>add</a>(action)</code> 
287          </td>
288        </tr>
289        <tr>
290          <td>
291            <code>multiaction_object <a href="/en/Marionette/Mari
>onette#multi_perform()" title="en/Marionette/Marionette#multi_per 
>form()">perform</a>()</code> 
292          </td>
293        </tr>
294        <tr>
295          <th>
296            Debugging
297          </th>
298        </tr>
299        <tr>
300          <td>
301            <code>None <a href="/en/Marionette/Marionette#log()" 
>title="en/Marionette/Marionette#log()">log</a>(msg, level)</code> 
302          </td>
303        </tr>
304        <tr>
305          <td>
306            <code>list <a href="/en/Marionette/Marionette#get_log
>s()" title="en/Marionette/Marionette#get_logs()">get_logs</a>()</ 
>code> 
307          </td>
308        </tr>
309        <tr>
310          <td>
311            <code>list <a href="/en/Marionette/Marionette#page_so
>urce()" title="en/Marionette/Marionette#page_source()">page_sourc 
>e</a>()</code> 
312          </td>
313        </tr>
314        <tr>
315          <td>
316            <code>str <a href="/en/Marionette/Marionette#page_sou
>rce()" title="en/Marionette/Marionette#page_source()"></a><a href 
>="#screenshot" title="#screenshot">screenshot()</a></code> 
317          </td>
318        </tr>
319      </tbody>
320    </table>
321    <h2 id="Attributes" name="Attributes">
322      Attributes
323    </h2>
324    <table class="standard-table">
325      <tbody>
326        <tr>
327          <td class="header">
328            Attribute
329          </td>
330          <td class="header">
331            Type
332          </td>
333          <td class="header">
334            Description
335          </td>
336        </tr>
337        <tr>
338          <td>
339            <code>emulator</code>
340          </td>
341          <td>
342            <a href="/en/Marionette/Emulator" title="en/Marionett
>e/Emulator"><code>Emulator</code></a> 
343          </td>
344          <td>
345            When tests are being run on a b2g emulator, an instan
>ce of Marionette's <a href="/en/Marionette/Emulator" title="en/Ma 
>rionette/Emulator"><code>Emulator</code></a> class, which allows  
>interaction with an emulator under test; otherwise <code>None</co 
>de>. 
346          </td>
347        </tr>
348        <tr>
349          <td>
350            <code>CONTEXT_CHROME</code>
351          </td>
352          <td>
353            <code>str</code>
354          </td>
355          <td>
356            A constant for the "chrome" context, used in <code>se
>t_context()</code>. 
357          </td>
358        </tr>
359        <tr>
360          <td>
361            <code>CONTEXT_CONTENT</code>
362          </td>
363          <td>
364            <code>str</code>
365          </td>
366          <td>
367            A constant for the "content" context, used in <code>s
>et_context()</code>. 
368          </td>
369        </tr>
370      </tbody>
371    </table>
372    <h2 id="Script_Execution_Methods">
373      Script Execution Methods
374    </h2>
375    <h3 id="execute_script()" name="execute_script()">
376      execute_script(script, script_args=None, special_powers=Fal
>se, new_sandbox=True) 
377    </h3>
378    <p>
379      Executes a synchronous JavaScript script, and returns the r
>esult.&nbsp; The script is executed in the context set by the mos 
>t recent <code>set_context()</code> call, or to the <code>CONTEXT 
>_CONTENT</code> context if <code>set_context()</code> has not bee 
>n called. 
380    </p>
381    <p>
382      For example:
383    </p>
384    <pre class="brush: python">
385class TestSomething(MarionetteTestCase):
386 
387    def test_foo(self):
388        result = self.marionette.execute_script("return 1;")
389        self.assertEqual(result, 1, "invalid execute_script resul
>t") 
390</pre>
391    <p>
392      Scripts wishing to access non-standard properties of the <c
>ode>window</code> object must use <code>window.wrappedJSObject</c 
>ode>.&nbsp; For example: 
393    </p>
394    <pre class="brush: python">
395class TestSomething(MarionetteTestCase):
396 
397    def test_foo(self):
398        result = self.marionette.execute_script("""
399          window.wrappedJSObject.test1 = 'foo';
400          window.wrappedJSObject.test2 = 'bar';
401          return window.wrappedJSObject.test1 + window.wrappedJSO
>bject.test2; 
402        """)
403        self.assertEqual(result, 'foobar', "invalid execute_scrip
>t result") 
404</pre>
405    <p>
406      Global variables set by individual scripts do not persist b
>etween script calls by default.&nbsp; If you wish to persist data 
> between script calls, you can set new_sandbox to False on your n 
>ext call, and add any new variables to the 'global' object like s 
>o: 
407    </p>
408    <pre class="brush: python">
409class TestSomething(MarionetteTestCase):
410 
411    def test_foo(self):
412        self.marionette.execute_script("global.test1 = 'foo';")
413        result = self.marionette.execute_script("return global.te
>st1;", new_sandbox=False) 
414        self.assertEqual(result, 'foo', "invalid execute_script r
>esult") 
415</pre>
416    <p>
417      You can also just use properties of the <code>window</code>
> object.&nbsp; For example: 
418    </p>
419    <pre class="brush: python">
420class TestSomething(MarionetteTestCase):
421 
422    def test_foo(self):
423        self.marionette.execute_script("window.wrappedJSObject.te
>st1 = 'foo';") 
424        result = self.marionette.execute_script("return window.wr
>appedJSObject.test1;") 
425        self.assertEqual(result, 'foo', "invalid execute_script r
>esult") 
426</pre>
427    <h5 id="Parameters">
428      Parameters
429    </h5>
430    <p>
431      <strong>script</strong> - a string containing the JavaScrip
>t to execute 
432    </p>
433    <p>
434      <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_scop 
>e/arguments" title="en/JavaScript/Reference/Functions_and_functio 
>n_scope/arguments"><code>arguments</code></a> object.&nbsp; For e 
>xample: 
435    </p>
436    <pre class="brush: python">
437class TestSomething(MarionetteTestCase):
438 
439    def test_foo(self):
440        result = self.marionette.execute_script("return arguments
>[0] + arguments[1];", script_args=[2, 3]) 
441        self.assertEqual(result, 5, "invalid execute_script resul
>t") 
442        some_element = self.marionette.find_element("id", "someEl
>ement") 
443        sid = self.marionette.execute_script("return arguments[0]
>.id;", script_args=[some_element]) 
444        self.assertEqual(some_element.get_attribute("id"), sid)
445</pre>
446    <p>
447      <strong>special_powers</strong> - whether or not you want a
>ccess to https://developer.mozilla.org/en-US/docs/SpecialPowers i 
>n your script. Set to False by default because it shouldn't reall 
>y be used, since you already have access to chrome-level commands 
> if you set context to chrome and do an execute_script. This meth 
>od was added only to help us run existing Mochitests. 
448    </p>
449    <p>
450      <strong>new_sandbox</strong> - if set to False, it will pre
>serve your global variables from the last execute_*script call. T 
>his is True by default, where no globals are preserved. 
451    </p>
452    <h5 id="Return_value">
453      Return value
454    </h5>
455    <p>
456      The return value of the script, or <code>None</code> if the
> script does not return a value. 
457    </p>
458    <h3 id="execute_async_script()" name="execute_async_script()"
>> 
459      execute_async_script(script, script_args=None, special_powe
>rs=False, new_sandbox=True) 
460    </h3>
461    <p>
462      Executes an asynchronous JavaScript script, and returns the
> result.&nbsp; The script is executed in the context set by the m 
>ost recent <code>set_context()</code> call, or to the <code>CONTE 
>XT_CONTENT</code> context if <code>set_context()</code> has not b 
>een called.&nbsp; Asynchronous scripts return a value by calling  
>the <code>marionetteScriptFinished()</code> function within the s 
>cript, or will throw a <code>ScriptTimeoutException</code> if the 
> timeout period, set by <code>set_script_timeout()</code>, is exc 
>eeded or not set.&nbsp; For example: 
463    </p>
464    <pre class="brush: python">
465class TestSomething(MarionetteTestCase):
466 
467    def test_foo(self):
468        self.marionette.<code>set_script_timeout</code>(10000); #
>set timeout period of 10 seconds 
469        result = self.marionette.execute_async_script("""
470          // this script waits 5 seconds, and then returns the nu
>mber 1 
471          setTimeout(function() {
472            marionetteScriptFinished(1);
473          }, 5000);
474        """)
475        self.assertEqual(result, 1, "invalid execute_async_script
> result") 
476</pre>
477    <p>
478      The same limitations regarding global variables and accessi
>ng the <code>window</code> object as described for <code>execute_ 
>script()</code> apply to <code>execute_async_script()</code> as w 
>ell. 
479    </p>
480    <h5 id="Parameters">
481      Parameters
482    </h5>
483    <p>
484      <strong>script</strong> - a string containing the JavaScrip
>t to execute 
485    </p>
486    <p>
487      <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/Functio 
>ns_and_function_scope/arguments"><code>arguments</code></a> objec 
>t. See <a href="/en/Marionette/Marionette#execute_script()" title 
>="en/Marionette/Marionette#execute_script()">execute_script()</a> 
> for an example. 
488    </p>
489    <p>
490      <strong>special_powers</strong> - whether or not you want a
>ccess to https://developer.mozilla.org/en-US/docs/SpecialPowers i 
>n your script. Set to False by default because it shouldn't reall 
>y be used, since you already have access to chrome-level commands 
> if you set context to chrome and do an execute_script. This meth 
>od was added only to help us run existing Mochitests. 
491    </p>
492    <p>
493      <strong>new_sandbox</strong> - if set to False, it will pre
>serve your global variables from the last execute_*script call. T 
>his is True by default, where no globals are preserved. 
494    </p>
495    <h5 id="Return_value">
496      Return value
497    </h5>
498    <p>
499      The return value of the script, or <code>None</code> if the
> script does not return a value. 
500    </p>
501    <h3 id="import_script()" name="import_script()">
502      import_script(file)
503    </h3>
504    <p>
505      Imports this script into the scope of the execute_script an
>d execute_async_script calls. This is particularly useful if you  
>wish to import your own libraries. 
506    </p>
507    <p>
508      Say you have a script, importfunc.js, that contains:
509    </p>
510    <pre class="brush: js">
511let testFunc = function() { return "i'm a test function!";};
512</pre>
513    <p>
514      You can now import this script and use it in an execute cal
>l. For example, assuming importfunc.js is in the same directory a 
>s the test: 
515    </p>
516    <pre class="brush: python">
517import os
518from marionette_test import MarionetteTestCase
519 
520class TestImportScript(MarionetteTestCase):
521    def test_import_script(self):
522        js = os.path.abspath(os.path.join(__file__, os.path.pardi
>r, "importfunc.js")) 
523        self.marionette.import_script(js)
524        self.assertEqual("i'm a test function!", self.marionette.
>execute_script("return testFunc();")) 
525</pre>
526    <p>
527      Imported scripts persist for the duration of the client's s
>ession. 
528    </p>
529    <h5 id="Parameters">
530      Parameters
531    </h5>
532    <p>
533      file - local file to upload to the marionette server
534    </p>
535    <h5 id="Return_value">
536      Return value
537    </h5>
538    <p>
539      None
540    </p>
541    <h3 id="set_script_timeout()" name="set_script_timeout()">
542      set_script_timeout(timeout)
543    </h3>
544    <p>
545      Sets the maximum number of ms that an asynchronous script i
>s allowed to run; if it doesn't return in the specified amount of 
> time, a <code>ScriptTimeoutException</code> is raised. 
546    </p>
547    <h5 id="Parameters">
548      Parameters
549    </h5>
550    <p>
551      timeout - the maximum number of milliseconds an asynchronou
>s script can run without causing an <code>ScriptTimeoutException< 
>/code> to be raised 
552    </p>
553    <h5 id="Return_value">
554      Return value
555    </h5>
556    <p>
557      None
558    </p>
559    <h2 id="Context_Management_Methods">
560      Context Management Methods
561    </h2>
562    <h3 id="set_context()" name="set_context()">
563      <a name="session_capabilities" id="session_capabilities">se
>ssion_capabilities</a> 
564    </h3>
565    <p>
566      This returns the current capabilities of the browser as a J
>SON Blob 
567    </p>
568    <h5 id="Parameters">
569      Parameters
570    </h5>
571    <p>
572      None
573    </p>
574    <h5 id="Return_value">
575      Return value
576    </h5>
577    <p>
578      A JSON string that mentioned
579    </p>
580    <h3 id="set_context()" name="set_context()">
581      set_context(context)
582    </h3>
583    <p>
584      Sets the context in which all subsequent commands will oper
>ate.&nbsp; The <code>CONTEXT_CONTENT</code> context is active unt 
>il this method is called for the first time.&nbsp; The active con 
>text impacts subsequent commands in different ways.&nbsp; For exa 
>mple, <code>execute_script()</code> calls in CONTEXT_CONTENT will 
> not have access to XPCOM objects, but they will in <code>CONTEXT 
>_CHROME</code>. 
585    </p>
586    <h5 id="Parameters">
587      Parameters
588    </h5>
589    <p>
590      <strong>context</strong> - one of <code>CONTEXT_CHROME</cod
>e> or <code>CONTEXT_CONTENT</code> 
591    </p>
592    <h5 id="Return_value">
593      Return value
594    </h5>
595    <p>
596      None
597    </p>
598    <h3 id="switch_to_frame()" name="switch_to_frame()">
599      switch_to_frame(frame_ref)
600    </h3>
601    <p>
602      Switch the current context to the specified frame.&nbsp; Su
>bsequent commands will operate in the context of the specified fr 
>ame, if applicable.&nbsp; An example relevant to B2G and Gaia: 
603    </p>
604    <pre class="brush: python">
605class TestSomething(MarionetteTestCase):
606 
607    def test_foo(self):
608        self.marionette.set_context(self.marionette.CONTEXT_CHROM
>E) 
609        # launch the clock app, which causes a new frame to be op
>ened 
610        self.marionette.execute_script("window.wrappedJSObject.Ga
>ia.AppManager.launch('../clock/clock.html')") 
611        # 'clock' shouldn't be in the href of the current frame, 
>which is the top-level frame for the main window 
612        self.assertTrue("clock.html" not in self.marionette.execu
>te_script("return document.location.href;")) 
613        # switch to the first child frame, which should be the cl
>ock app 
614        self.marionette.switch_to_frame(0)
615        # 'clock' *should* now be in the href of the current fram
>e 
616        self.assertTrue("clock.html" in self.marionette.execute_s
>cript("return document.location.href;"))         
617</pre>
618    <h5 id="Parameters">
619      Parameters
620    </h5>
621    <p>
622      <strong>frame_ref</strong> - a reference to the frame you w
>ant 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. 
623    </p>
624    <h5 id="Return_value">
625      Return value
626    </h5>
627    <p>
628      None
629    </p>
630    <h3 id="switch_to_window()" name="switch_to_window()">
631      switch_to_window(window_ref)
632    </h3>
633    <p>
634      Switch to the specified window; subsequent commands will be
> directed at the new window. 
635    </p>
636    <h5 id="Parameters">
637      Parameters
638    </h5>
639    <p>
640      window_ref - the id or name of the window to switch to
641    </p>
642    <h5 id="Return_value">
643      Return value
644    </h5>
645    <p>
646      None
647    </p>
648    <h3 id="get_window()" name="get_window()">
649      <a name="current_window_handle" id="current_window_handle">
>current_window_handle</a> 
650    </h3>
651    <p>
652      Returns a reference to the current window.
653    </p>
654    <h5 id="Parameters">
655      Parameters
656    </h5>
657    <p>
658      None
659    </p>
660    <h5 id="Return_value">
661      Return value
662    </h5>
663    <p>
664      A reference to the current window.&nbsp; This reference can
> be used in later calls to <code>switch_to_window()</code>. 
665    </p>
666    <h3 id="get_windows()" name="get_windows()">
667      <a name="window_handles" id="window_handles">window_handles
></a> 
668    </h3>
669    <p>
670      Returns a list of references to all available browser windo
>ws if called in content. If called while in the chrome context, i 
>t will list all available windows, not just browser windows (ie:  
>not just 'navigator:browser';). 
671    </p>
672    <h5 id="Parameters">
673      Parameters
674    </h5>
675    <p>
676      None
677    </p>
678    <h5 id="Return_value">
679      Return value
680    </h5>
681    <p>
682      A list of references to all available windows.&nbsp; These 
>references can be used in later calls to <code>switch_to_window() 
></code>. 
683    </p>
684    <h3 id="close()">
685      <a name="close()">close()</a>
686    </h3>
687    <p>
688      This closes the window that is in use by Marionette
689    </p>
690    <h5 id="Parameters">
691      Parameters
692    </h5>
693    <p>
694      Window ID of the window you wish to closed
695    </p>
696    <h2 id="Navigation_Methods">
697      Navigation Methods
698    </h2>
699    <h3 id="navigate()" name="navigate()">
700      navigate(url)
701    </h3>
702    <p>
703      Causes the browser to navigate to the specified url.
704    </p>
705    <h5 id="Parameters">
706      Parameters
707    </h5>
708    <p>
709      url - the url to navigate to
710    </p>
711    <h5 id="Return_value">
712      Return value
713    </h5>
714    <p>
715      None
716    </p>
717    <h3 id="get_url()" name="get_url()">
718      get_url()
719    </h3>
720    <p>
721      Returns the url of the active page in the browser.
722    </p>
723    <h5 id="Parameters">
724      Parameters
725    </h5>
726    <p>
727      None
728    </p>
729    <h5 id="Return_value">
730      Return value
731    </h5>
732    <p>
733      The url of the active page in the browser.
734    </p>
735    <h3 id="go_back()" name="go_back()">
736      go_back()
737    </h3>
738    <p>
739      Causes the browser to perform a back navigation.
740    </p>
741    <h5 id="Parameters">
742      Parameters
743    </h5>
744    <p>
745      None
746    </p>
747    <h5 id="Return_value">
748      Return value
749    </h5>
750    <p>
751      None
752    </p>
753    <h3 id="go_forward()" name="go_forward()">
754      go_forward()
755    </h3>
756    <p>
757      Causes the browser to perform a forward navigation.
758    </p>
759    <h5 id="Parameters">
760      Parameters
761    </h5>
762    <p>
763      None
764    </p>
765    <h5 id="Return_value">
766      Return value
767    </h5>
768    <p>
769      None
770    </p>
771    <h3 id="refresh()" name="refresh()">
772      refresh()
773    </h3>
774    <p>
775      Causes the browser to perform to refresh the current page.
776    </p>
777    <h5 id="Parameters">
778      Parameters
779    </h5>
780    <p>
781      None
782    </p>
783    <h5 id="Return_value">
784      Return value
785    </h5>
786    <p>
787      None
788    </p>
789    <h3 id="absolute_url()" name="absolute_url()">
790      absolute_url(url)
791    </h3>
792    <p>
793      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. 
794    </p>
795    <h5 id="Parameters">
796      Parameters
797    </h5>
798    <p>
799      <strong>url</strong> - the url of a static file, relative t
>o Marionette's <code>www</code> directory. 
800    </p>
801    <h5 id="Return_value">
802      Return value
803    </h5>
804    <p>
805      The absolute url for the file, which can be used, for examp
>le, in calls to <code>navigate()</code>. 
806    </p>
807    <p>
808      &nbsp;
809    </p>
810    <h2 id="DOM_Element_Methods">
811      DOM Element Methods
812    </h2>
813    <p>
814      &nbsp;
815    </p>
816    <h3 id="set_search_timeout()" name="set_search_timeout()">
817      set_search_timeout(timeout)
818    </h3>
819    <p>
820      When searching for an element using either of the <code>fin
>d_</code> methods, the method will continue trying to locate the  
>element for up to <code>timeout</code> ms.&nbsp; This can be usef 
>ul if, for example, the element you're looking for might not exis 
>t immediately, because it belongs to a page which is currently be 
>ing loaded. 
821    </p>
822    <p>
823      After this period of time, if the element is not found, a <
>code>NoSuchElementException</code> will be raised. 
824    </p>
825    <h5 id="Parameters">
826      Parameters
827    </h5>
828    <p>
829      <strong>timeout</strong> - the max number of ms to search f
>or elements using the <code>find_</code> methods before raising a 
> <code>NoSuchElementException</code>. 
830    </p>
831    <h5 id="Return_value">
832      Return value
833    </h5>
834    <p>
835      None
836    </p>
837    <h3 id="find_element()" name="find_element()">
838      find_element(method, target)
839    </h3>
840    <p>
841      Returns an <code>HTMLElement</code> instance for the specif
>ied element in the current context.&nbsp; An <code>HTMLElement</c 
>ode> instance may be used to call other methods on the element, s 
>uch as <code>click()</code>.&nbsp; If no element is immediately f 
>ound, the attempt to locate an element will be repeated for up to 
> the amount of time set by <code>set_search_timeout()</code>. 
842    </p>
843    <h5 id="Parameters">
844      Parameters
845    </h5>
846    <p>
847      <strong>method</strong> - the method to use to locate the e
>lement; one of: "id", "name", "class name", "tag name", "css sele 
>ctor", "link text", "partial link text" and "xpath". Note that th 
>e methods supported in the chrome dom are only "id", "class name" 
>, "tag name" and "xpath". 
848    </p>
849    <p>
850      <strong>target</strong> - the target of the search.&nbsp; F
>or example, if <code>method</code> = "tag", <code>target</code> m 
>ight equal "div".&nbsp; If <code>method</code> = "id", <code>targ 
>et</code> would be an element id. 
851    </p>
852    <h5 id="Return_value">
853      Return value
854    </h5>
855    <p>
856      An <code>HTMLElement</code> instance corresponding to the s
>pecified criteria.&nbsp; If multiple elements match the given cri 
>teria, only the first is returned.&nbsp; If no element matches, a 
> <code>NoSuchElementException</code> will be raised. 
857    </p>
858    <h3 id="find_elements()" name="find_elements()">
859      find_elements(method, target)
860    </h3>
861    <p>
862      Returns a list of all <code>HTMLElement</code> instances th
>at match the specified method and target in the current context.& 
>nbsp; An <code>HTMLElement</code> instance may be used to call ot 
>her methods on the element, such as <code>click()</code>.&nbsp; I 
>f no element is immediately found, the attempt to locate an eleme 
>nt will be repeated for up to the amount of time set by <code>set 
>_search_timeout()</code>. 
863    </p>
864    <h5 id="Parameters">
865      Parameters
866    </h5>
867    <p>
868      <strong>method</strong> - the method to use to locate the e
>lement; one of: "id", "name", "class name", "tag name", "css sele 
>ctor", "link text", "partial link text" and "xpath". Note that th 
>e methods supported in the chrome dom are only "id", "class name" 
>, "tag name" and "xpath". 
869    </p>
870    <p>
871      <strong>target</strong> - the target of the search.&nbsp; F
>or example, if <code>method</code> = "tag", <code>target</code> m 
>ight equal "div".&nbsp; If <code>method</code> = "id", <code>targ 
>et</code> would be an element id. 
872    </p>
873    <h5 id="Return_value">
874      Return value
875    </h5>
876    <p>
877      A list of <code>HTMLElement</code> instances corresponding 
>to the specified criteria. If no element matches, a <code>NoSuchE 
>lementException</code> will be raised. 
878    </p>
879    <h3 id="find_elements()" name="find_elements()">
880      get_attribute(attribute)
881    </h3>
882    <p>
883      Returns the requested attribute.
884    </p>
885    <h5 id="Parameters">
886      Parameters
887    </h5>
888    <p>
889      <strong>attribute</strong> - the name of the attribute.
890    </p>
891    <h5 id="Return_value">
892      Return value
893    </h5>
894    <p>
895      The attribute, or None if no value is set.
896    </p>
897    <h3 id="find_elements()" name="find_elements()">
898      text
899    </h3>
900    <p>
901      Returns the visible text of the element, and its child elem
>ents. 
902    </p>
903    <h5 id="Parameters">
904      Parameters
905    </h5>
906    <p>
907      None
908    </p>
909    <h5 id="Return_value">
910      Return value
911    </h5>
912    <p>
913      The visible text, with the text of its child elements separ
>ated by newlines. 
914    </p>
915    <h3 id="find_elements()" name="find_elements()">
916      send_keys(String)
917    </h3>
918    <p>
919      Sends the string via synthesized keypresses to the element.
920    </p>
921    <h5 id="Parameters">
922      Parameters
923    </h5>
924    <p>
925      <strong>string</strong> - the string to be sent to the elem
>ent. 
926    </p>
927    <h5 id="Return_value">
928      Return value
929    </h5>
930    <p>
931      None
932    </p>
933    <h3 id="find_elements()" name="find_elements()">
934      clear()
935    </h3>
936    <p>
937      Clear the input of the element.
938    </p>
939    <h5 id="Parameters">
940      Parameters
941    </h5>
942    <p>
943      None
944    </p>
945    <h5 id="Return_value">
946      Return value
947    </h5>
948    <p>
949      None
950    </p>
951    <h3 id="find_elements()" name="find_elements()">
952      click()
953    </h3>
954    <p>
955      Click the element.
956    </p>
957    <h5 id="Parameters">
958      Parameters
959    </h5>
960    <p>
961      None
962    </p>
963    <h5 id="Return_value">
964      Return value
965    </h5>
966    <p>
967      None
968    </p>
969    <h3 id="find_elements()" name="find_elements()">
970      <a name="is_selected()">is_selected()</a>
971    </h3>
972    <p>
973      Check if the element is selected.
974    </p>
975    <h5 id="Parameters">
976      Parameters
977    </h5>
978    <p>
979      None
980    </p>
981    <h5 id="Return_value">
982      Return value
983    </h5>
984    <p>
985      Returns true if the element is selected, false otherwise.
986    </p>
987    <h3 id="find_elements()" name="find_elements()">
988      <a name="is_enabled()">is_enabled()</a>
989    </h3>
990    <p>
991      Check if the element is enabled.
992    </p>
993    <h5 id="Parameters">
994      Parameters
995    </h5>
996    <p>
997      None
998    </p>
999    <h5 id="Return_value">
1000      Return value
1001    </h5>
1002    <p>
1003      Returns true if the element is enabled, false otherwise.
1004    </p>
1005    <h3 id="find_elements()" name="find_elements()">
1006      <a name="is_displayed()">is_displayed()</a>
1007    </h3>
1008    <p>
1009      Check if the element is displayed.
1010    </p>
1011    <h5 id="Parameters">
1012      Parameters
1013    </h5>
1014    <p>
1015      None
1016    </p>
1017    <h5 id="Return_value">
1018      Return value
1019    </h5>
1020    <p>
1021      Returns true if the element is displayed, false otherwise.
1022    </p>
1023    <h3 id="find_elements()" name="find_elements()">
1024      <a name="tag_name" id="tag_name">tag_name</a>
1025    </h3>
1026    <p>
1027      Get the tag name of the element
1028    </p>
1029    <h5 id="Parameters">
1030      Parameters
1031    </h5>
1032    <p>
1033      None
1034    </p>
1035    <h5 id="Return_value">
1036      Return value
1037    </h5>
1038    <p>
1039      Returns a string of what the element tag name is.
1040    </p>
1041    <h3 id="find_elements()" name="find_elements()">
1042      <a name="size" id="size">size</a>
1043    </h3>
1044    <p>
1045      Get the size of the element
1046    </p>
1047    <h5 id="Parameters">
1048      Parameters
1049    </h5>
1050    <p>
1051      None
1052    </p>
1053    <h5 id="Return_value">
1054      Return value
1055    </h5>
1056    <p>
1057      Returns a dictionary with the height and width of the eleme
>nt 
1058    </p>
1059    <h3 id="find_elements()" name="find_elements()">
1060      <a name="location" id="location">location</a>
1061    </h3>
1062    <p>
1063      Get the location of the element
1064    </p>
1065    <h5 id="Parameters">
1066      Parameters
1067    </h5>
1068    <p>
1069      None
1070    </p>
1071    <h5 id="Return_value">
1072      Return value
1073    </h5>
1074    <p>
1075      Returns a dictionary with the x and y location of an elemen
>t 
1076    </p>
1077    <h3 id="single_tap(x,y)" name="single_tap(x,y)">
1078      <a name="single_tap(x,y)">tap(x, y)</a>
1079    </h3>
1080    <p>
1081      Sends 'touchstart', 'touchend', 'mousedown', 'mouseup', 'mo
>useclick' events to this element (which is the default set of eve 
>nts sent to a touch device). 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 corne 
>r of the element. 
1082    </p>
1083    <h5 id="Parameters">
1084      Parameters
1085    </h5>
1086    <p>
1087      <strong>x</strong> - optional, x-coordinate to tap, relativ
>e to the top-left corner of the element 
1088    </p>
1089    <p>
1090      <strong>y</strong> - optional, y-coordinate to tap, relativ
>e to the top-left corner of the element 
1091    </p>
1092    <h5 id="Return_value">
1093      Return value
1094    </h5>
1095    <p>
1096      None
1097    </p>
1098    <h2 id="Action_Chain_Methods">
1099      <a name="action_chain" id="action_chain">Action Chain Metho
>ds</a> 
1100    </h2>
1101    <p>
1102      "Action chain" will be used to denote a set of actions that
> have to be executed in particular order, and will allow simultan 
>eous execution of parallel chains so we can have 'multifinger' ge 
>stures. A general example of an action chain is: 
1103    </p>
1104    <pre class="brush: python">
1105class TestSomething(MarionetteTestCase):
1106 
1107 
1108    def test_foo(self):
1109        # get html file
1110        testAction = self.marionette.absolute_url("testFool.html"
>) 
1111        # navigate to the file
1112        self.marionette.navigate(testAction)
1113        # find element1 and element2
1114        element1 = self.marionette.find_element("id", "element1")
1115        element2 = self.marionette.find_element("id", "element2")
1116        # create action object
1117        action = Actions(marionette)
1118        # add actions (press, wait, move, release) into the objec
>t 
1119        action.press(element1).wait(5). move(element2).release()
1120        # fire all the added events
1121        action.perform()
1122</pre>
1123    <p>
1124      This action chain will do a press() on element1, then wait 
>5 seconds, then move to element2, then, release on element2. 
1125    </p>
1126    <p>
1127      <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. 
1128    </p>
1129    <p>
1130      <strong>NOTE2</strong>: Action chain can be performed in se
>gments. An example of element2 displays only after element1 makes 
> use of this. 
1131    </p>
1132    <pre class="brush: python">
1133class TestSomething(MarionetteTestCase):
1134 
1135 
1136    def test_foo(self):
1137        # get html file
1138        testAction = self.marionette.absolute_url("testFool.html"
>) 
1139        # navigate to the file
1140        self.marionette.navigate(testAction)
1141        # create an object
1142        action = Actions(marionette)
1143        # find element1    
1144        element1 = self.marionette.find_element("id", element1")
1145        # press on element1
1146        action.press(element1).perform()
1147        # now find element2    
1148        element2 = self.marionette.find_element("id", element2")
1149        # same action object which move finger from element1 to e
>lement2, and then release at element2     
1150        action.move(element2).release().perform()
1151</pre>
1152    <p>
1153      <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 <a href="#multi_action" title="#multi_action" 
>>MultiAction</a> methods. 
1154    </p>
1155    <p>
1156      <strong>NOTE4</strong>: If the action chain performs a long
> press, contextmenu event will be fired. 
1157    </p>
1158    <h3 id="press(element,x,y)" name="press(element,x,y)">
1159      <a name="press(element,x,y)">press(element, x=None, y=None)
></a> 
1160    </h3>
1161    <p>
1162      Sends a 'touchstart' event to this element. If no coordinat
>es are given, it will be targeted at the center of the element. I 
>f given, it will be targeted at the (x,y) coordinates relative to 
> the top-left corner of the element. 
1163    </p>
1164    <h5 id="Parameters">
1165      Parameters
1166    </h5>
1167    <p>
1168      <strong>element</strong> - the element to press on
1169    </p>
1170    <p>
1171      <strong>x</strong> - optional, x-coordinate to tap, relativ
>e to the top-left corner of the element 
1172    </p>
1173    <p>
1174      <strong>y</strong> - optional, y-coordinate to tap, relativ
>e to the top-left corner of the element 
1175    </p>
1176    <h5 id="Return_value">
1177      Return value
1178    </h5>
1179    <p>
1180      Returns the object itself
1181    </p>
1182    <h3 id="release()" name="release()">
1183      <a name="release()">release()</a>
1184    </h3>
1185    <p>
1186      release() can only be called if press() has already be call
>ed on this element. 
1187    </p>
1188    <p>
1189      release() send 'touchend' event to whenever the finger is
1190    </p>
1191    <h5 id="Parameters">
1192      Parameters
1193    </h5>
1194    <p>
1195      None
1196    </p>
1197    <h5 id="Return_value">
1198      Return value
1199    </h5>
1200    <p>
1201      Returns the object itself
1202    </p>
1203    <h3 id="move(element)" name="move(element)">
1204      <a name="move(element)">move(element)</a>
1205    </h3>
1206    <p>
1207      move() can only be called if press() has already be called 
>on this element. 
1208    </p>
1209    <p>
1210      move(element) send 'touchmove' event which moves the finger
> to target element 
1211    </p>
1212    <h5 id="Parameters">
1213      Parameters
1214    </h5>
1215    <p>
1216      <strong>element</strong> - the target element of the move g
>esture 
1217    </p>
1218    <h5 id="Return_value">
1219      Return value
1220    </h5>
1221    <p>
1222      Returns the object itself
1223    </p>
1224    <h3 id="move_by_offset(x,y)" name="move_by_offset(x,y)">
1225      <a name="move_by_offset(x,y)">move_by_offset(x, y)</a>
1226    </h3>
1227    <p>
1228      move_by_offset() can only be called if press() has already 
>be called on this element. 
1229    </p>
1230    <p>
1231      move_by_offset(x, y) send 'touchmove' event
1232    </p>
1233    <h5 id="Parameters">
1234      Parameters
1235    </h5>
1236    <p>
1237      <strong>x</strong> - x-coordinate relative to the top-left 
>corner of the target element of the last touch 
1238    </p>
1239    <p>
1240      <strong>y</strong> - y-coordinate relative to the top-left 
>corner of the target element of the last touch 
1241    </p>
1242    <h5 id="Return_value">
1243      Return value
1244    </h5>
1245    <p>
1246      Returns the object itself
1247    </p>
1248    <h3 id="wait(time)" name="wait(time)">
1249      <a name="wait(time)">wait(time=None)</a>
1250    </h3>
1251    <p>
1252      wait(time) wait for specified time period
1253    </p>
1254    <h5 id="Parameters">
1255      Parameters
1256    </h5>
1257    <p>
1258      <strong>time</strong> - wait for "time" seconds
1259    </p>
1260    <h5 id="Return_value">
1261      Return value
1262    </h5>
1263    <p>
1264      Returns the object itself
1265    </p>
1266    <h3 id="cancel()" name="cancel()">
1267      <a name="cancel()">cancel()</a>
1268    </h3>
1269    <p>
1270      cancel() can only be called if press() has already be calle
>d on this element. 
1271    </p>
1272    <p>
1273      cancel() send 'touchcancel' event to whenever the finger is
1274    </p>
1275    <h5 id="Parameters">
1276      Parameters
1277    </h5>
1278    <p>
1279      None
1280    </p>
1281    <h5 id="Return_value">
1282      Return value
1283    </h5>
1284    <p>
1285      Returns the object itself
1286    </p>
1287    <h3 id="cancel()" name="cancel()">
1288      <a name="long_press(element,time_in_seconds)">long_press(el
>ement, time_in_seconds)</a> 
1289    </h3>
1290    <p>
1291      long_press(element, time_in_seconds) triggers a sequence of
> touch events. 
1292    </p>
1293    <p>
1294      It sends 'touchstart', then wait for 'time_in_seconds' seco
>nds, and send 'touchend' eventually. 
1295    </p>
1296    <p>
1297      long_press(element, time_in_seconds) cannot follow any acti
>ve touch, i.e. the finger must leave the screen before long_press 
> gets called. 
1298    </p>
1299    <h5 id="Parameters">
1300      Parameters
1301    </h5>
1302    <p>
1303      <strong>element</strong> - the target element of the long p
>ress 
1304    </p>
1305    <p>
1306      <strong>time_in_seconds</strong> - the waiting time between
> touchstart and touchend 
1307    </p>
1308    <h5 id="Return_value">
1309      Return value
1310    </h5>
1311    <p>
1312      Returns the object itself
1313    </p>
1314    <h3 id="cancel()" name="cancel()">
1315      <a name="flick(element,x1,y1,x2,y2,duration)">flick(element
>, x1, y1, x2, y2, duration=200)</a> 
1316    </h3>
1317    <p>
1318      flick(element, x1, y1, x2, y2) sends a sequence of touch ev
>ents: touchstart, touchmove, touchend. 
1319    </p>
1320    <p>
1321      It scrolls the page in any direction within period of time 
>provided(duration). 
1322    </p>
1323    <h5 id="Parameters">
1324      Parameters
1325    </h5>
1326    <p>
1327      <strong>element</strong> - the element that all coordinates
> relate to 
1328    </p>
1329    <p>
1330      <strong>x1</strong> - starting x-coordinates of the finger 
>relative to the element 
1331    </p>
1332    <p>
1333      <strong>y1</strong> - starting y-coordinates of the finger 
>relative to the element 
1334    </p>
1335    <p>
1336      <strong>x2</strong> - ending x-coordinates of the finger re
>lative to the element 
1337    </p>
1338    <p>
1339      <strong>y2</strong> - ending y-coordinates of the finger re
>lative to the element 
1340    </p>
1341    <p>
1342      <strong>duration</strong> - optional, time needed for the f
>lick gesture for complete 
1343    </p>
1344    <h5 id="Return_value">
1345      Return value
1346    </h5>
1347    <p>
1348      Returns the object itself
1349    </p>
1350    <h3 id="cancel()" name="cancel()">
1351      <a name="tap(element,x,y)">tap(element, x=None, y=None)</a>
1352    </h3>
1353    <p>
1354      tap() performs a quick tap on the target, i.e. (x, y) relat
>ive to the element. 
1355    </p>
1356    <p>
1357      action.tap(element, x, y).perform() is essentially action.p
>ress(element, x, y).release().press(element, x, y).release() 
1358    </p>
1359    <h5 id="Parameters">
1360      Parameters
1361    </h5>
1362    <p>
1363      <strong>element</strong> - the element to press/release on
1364    </p>
1365    <p>
1366      <strong>x</strong> - optional, x-coordinate to tap, relativ
>e to the top-left corner of the element 
1367    </p>
1368    <p>
1369      <strong>y</strong> - optional, y-coordinate to tap, relativ
>e to the top-left corner of the element 
1370    </p>
1371    <h5 id="Return_value">
1372      Return value
1373    </h5>
1374    <p>
1375      Returns the object itself
1376    </p>
1377    <h3 id="cancel()" name="cancel()">
1378      <a name="double_tap(element,x,y)">double_tap(element, x=Non
>e, y=None)</a> 
1379    </h3>
1380    <p>
1381      double_tap(element, x, y) performs a double tap on the targ
>et. 
1382    </p>
1383    <h5 id="Parameters">
1384      Parameters
1385    </h5>
1386    <p>
1387      <strong>element</strong> - the element to double tap on
1388    </p>
1389    <p>
1390      <strong>x</strong> - optional, x-coordinate to tap, relativ
>e to the top-left corner of the element 
1391    </p>
1392    <p>
1393      <strong>y</strong> - optional, y-coordinate to tap, relativ
>e to the top-left corner of the element 
1394    </p>
1395    <h5 id="Return_value">
1396      Return value
1397    </h5>
1398    <p>
1399      Returns the object itself
1400    </p>
1401    <h3 id="perform()" name="perform()">
1402      <a name="perform()">perform()</a>
1403    </h3>
1404    <p>
1405      perform() will send the whole action chain built so far to 
>the server side for execution. 
1406    </p>
1407    <h5 id="Parameters">
1408      Parameters
1409    </h5>
1410    <p>
1411      None
1412    </p>
1413    <h5 id="Return_value">
1414      Return value
1415    </h5>
1416    <p>
1417      Returns the object itself
1418    </p>
1419    <h2 id="Multiaction_Methods">
1420      <a name="multi_action" id="multi_action">Multiaction Method
>s</a> 
1421    </h2>
1422    <p>
1423      For a multifinger gesture, we can employ MultiActions. For 
>example, say you want one finger to hold down while the other fin 
>ger moves from one element to another, we propose doing this in t 
>he client: 
1424    </p>
1425    <pre class="brush: python">
1426class TestSomething(MarionetteTestCase):
1427 
1428 
1429    def test_foo(self):
1430        # get html file
1431        testAction = self.marionette.absolute_url("testFool.html"
>) 
1432        # navigate to the file
1433        self.marionette.navigate(testAction)
1434        # find element1 and element2
1435        element1 = self.marionette.find_element("id", "element1")
1436        element2 = self.marionette.find_element("id", "element2")
1437        element3 = self.marionette.find_element("id", "element3")
1438        # create multiaction object
1439        multitouch = MultiActions(marionette)
1440        # create several action objects
1441        action_1 = Actions(marionette)
1442        action_2 = Actions(marionette)
1443        # add actions to each action object/finger
1444        action_1.press(element1).move_to(element2).release()
1445        action_2.press(element3).wait().release(element3)
1446        # fire all the added events
1447        multitouch.add(action_1).add(action_2).perform()
1448</pre>
1449    <p>
1450      <strong>NOTE</strong>: It will execute only when perform() 
>is called. 
1451    </p>
1452    <h3 id="add(action)" name="add(action)">
1453      <a name="add(action)">add(action)</a>
1454    </h3>
1455    <p>
1456      This method adds the action chain specified to the multiact
>ion object. 
1457    </p>
1458    <h5 id="Parameters">
1459      Parameters
1460    </h5>
1461    <p>
1462      <strong>action</strong> - one action object
1463    </p>
1464    <h5 id="Return_value">
1465      Return value
1466    </h5>
1467    <p>
1468      Returns the object itself
1469    </p>
1470    <h3 id="multi_perform()" name="multi_perform()">
1471      <a name="multi_perform()">perform()</a>
1472    </h3>
1473    <p>
1474      perform() will send multiple action chains that have been a
>dded so far to the server side for execution. 
1475    </p>
1476    <h5 id="Parameters">
1477      Parameters
1478    </h5>
1479    <p>
1480      None
1481    </p>
1482    <h5 id="Return_value">
1483      Return value
1484    </h5>
1485    <p>
1486      None
1487    </p>
1488    <h2 id="Debugging">
1489      Debugging
1490    </h2>
1491    <h3 id="log()" name="log()">
1492      log(msg, level)
1493    </h3>
1494    <p>
1495      You can log messages with this method
1496    </p>
1497    <p>
1498      &nbsp;
1499    </p>
1500    <h5 id="Parameters">
1501      Parameters
1502    </h5>
1503    <p>
1504      &nbsp;
1505    </p>
1506    <p>
1507      <strong>msg</strong> - The log message
1508    </p>
1509    <p>
1510      <strong>level</strong> - A custom log level. If not set, it
> defaults to "INFO" 
1511    </p>
1512    <h5 id="Return_value">
1513      Return value
1514    </h5>
1515    <p>
1516      None
1517    </p>
1518    <h3 id="get_logs()" name="get_logs()">
1519      get_logs()
1520    </h3>
1521    <p>
1522      Get all logs you made with the <code>log</code> method.
1523    </p>
1524    <h5 id="Parameters">
1525      Parameters
1526    </h5>
1527    <p>
1528      None
1529    </p>
1530    <h5 id="Return_value">
1531      Return value
1532    </h5>
1533    <p>
1534      List of log message strings
1535    </p>
1536    <h3 id="page_source()" name="page_source()">
1537      page_source()
1538    </h3>
1539    <p>
1540      Serialises the DOM into a string that can then be worked ag
>ainst. 
1541    </p>
1542    <h5 id="Parameters">
1543      Parameters
1544    </h5>
1545    <p>
1546      None
1547    </p>
1548    <h5 id="Return_value">
1549      Return value
1550    </h5>
1551    <p>
1552      A string representation of the document object
1553    </p>
1554    <h3 id="page_source()" name="page_source()">
1555      <a name="screenshot" id="screenshot">screenshot()</a>
1556    </h3>
1557    <p>
1558      Creates a base64.
1559    </p>
1560    <h5 id="Parameters">
1561      Parameters
1562    </h5>
1563    <p>
1564      None
1565    </p>
1566    <h5 id="Return_value">
1567      Return value
1568    </h5>
1569    <p>
1570      A base64 string representation of the document object

Back to History