2 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3 <html><head><title>Python: package telemetry</title>
4 </head><body bgcolor="#f0f0f8">
6 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
8 <td valign=bottom> <br>
9 <font color="#ffffff" face="helvetica, arial"> <br><big><big><strong>telemetry</strong></big></big></font></td
10 ><td align=right valign=bottom
11 ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="../telemetry/__init__.py">telemetry/__init__.py</a></font></td></tr></table>
12 <p><tt>A library for cross-platform browser tests.</tt></p>
14 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
15 <tr bgcolor="#aa55cc">
16 <td colspan=3 valign=bottom> <br>
17 <font color="#ffffff" face="helvetica, arial"><big><strong>Package Contents</strong></big></font></td></tr>
19 <tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td>
20 <td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="telemetry.core.html"><strong>core</strong> (package)</a><br>
21 <a href="telemetry.decorators.html">decorators</a><br>
22 <a href="telemetry.exception_formatter.html">exception_formatter</a><br>
23 </td><td width="25%" valign=top><a href="telemetry.page.html"><strong>page</strong> (package)</a><br>
24 <a href="telemetry.test.html">test</a><br>
25 <a href="telemetry.test_runner.html">test_runner</a><br>
26 </td><td width="25%" valign=top><a href="telemetry.unittest.html"><strong>unittest</strong> (package)</a><br>
27 <a href="telemetry.util.html"><strong>util</strong> (package)</a><br>
28 <a href="telemetry.value.html"><strong>value</strong> (package)</a><br>
29 </td><td width="25%" valign=top><a href="telemetry.web_components.html"><strong>web_components</strong> (package)</a><br>
30 </td></tr></table></td></tr></table><p>
31 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
32 <tr bgcolor="#ee77aa">
33 <td colspan=3 valign=bottom> <br>
34 <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
36 <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td>
38 <dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a>
41 <dt><font face="helvetica, arial"><a href="telemetry.core.browser.html#Browser">telemetry.core.browser.Browser</a>
44 <dt><font face="helvetica, arial"><a href="optparse.html#Values">optparse.Values</a>
47 <dt><font face="helvetica, arial"><a href="telemetry.core.browser_options.html#BrowserFinderOptions">telemetry.core.browser_options.BrowserFinderOptions</a>
50 <dt><font face="helvetica, arial"><a href="telemetry.core.web_contents.html#WebContents">telemetry.core.web_contents.WebContents</a>(<a href="__builtin__.html#object">__builtin__.object</a>)
53 <dt><font face="helvetica, arial"><a href="telemetry.core.tab.html#Tab">telemetry.core.tab.Tab</a>
56 <dt><font face="helvetica, arial"><a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a>(<a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a>)
59 <dt><font face="helvetica, arial"><a href="telemetry.page.page_measurement.html#PageMeasurement">telemetry.page.page_measurement.PageMeasurement</a>
64 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
65 <tr bgcolor="#ffc8d8">
66 <td colspan=3 valign=bottom> <br>
67 <font color="#000000" face="helvetica, arial"><a name="Browser">class <strong>Browser</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr>
69 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
70 <td colspan=2><tt>A running browser instance that can be controlled in a limited way.<br>
72 To create a browser instance, use browser_finder.FindBrowser.<br>
74 Be sure to clean up after yourself by calling <a href="#Browser-Close">Close</a>() when you are done with<br>
75 the browser. Or better yet:<br>
76 browser_to_create = FindBrowser(options)<br>
77 with browser_to_create.Create() as browser:<br>
78 ... do all your operations on browser here<br> </tt></td></tr>
80 <td width="100%">Methods defined here:<br>
81 <dl><dt><a name="Browser-Close"><strong>Close</strong></a>(self)</dt><dd><tt>Closes this browser.</tt></dd></dl>
83 <dl><dt><a name="Browser-GetStackTrace"><strong>GetStackTrace</strong></a>(self)</dt></dl>
85 <dl><dt><a name="Browser-GetStandardOutput"><strong>GetStandardOutput</strong></a>(self)</dt></dl>
87 <dl><dt><a name="Browser-GetSystemInfo"><strong>GetSystemInfo</strong></a>(self)</dt><dd><tt>Returns low-level information about the system, if available.<br>
89 See the documentation of the SystemInfo class for more details.</tt></dd></dl>
91 <dl><dt><a name="Browser-SetHTTPServerDirectories"><strong>SetHTTPServerDirectories</strong></a>(self, paths)</dt><dd><tt>Returns True if the HTTP server was started, False otherwise.</tt></dd></dl>
93 <dl><dt><a name="Browser-SetReplayArchivePath"><strong>SetReplayArchivePath</strong></a>(self, archive_path, append_to_existing_wpr<font color="#909090">=False</font>, make_javascript_deterministic<font color="#909090">=True</font>)</dt></dl>
95 <dl><dt><a name="Browser-Start"><strong>Start</strong></a>(self)</dt></dl>
97 <dl><dt><a name="Browser-StartLocalServer"><strong>StartLocalServer</strong></a>(self, server)</dt><dd><tt>Starts a LocalServer and associates it with this browser.<br>
99 It will be closed when the browser closes.</tt></dd></dl>
101 <dl><dt><a name="Browser-StartProfiling"><strong>StartProfiling</strong></a>(self, profiler_name, base_output_file)</dt><dd><tt>Starts profiling using |profiler_name|. Results are saved to<br>
102 |base_output_file|.<process_name>.</tt></dd></dl>
104 <dl><dt><a name="Browser-StartTracing"><strong>StartTracing</strong></a>(self, custom_categories<font color="#909090">=None</font>, timeout<font color="#909090">=10</font>)</dt></dl>
106 <dl><dt><a name="Browser-StopProfiling"><strong>StopProfiling</strong></a>(self)</dt><dd><tt>Stops all active profilers and saves their results.<br>
109 A list of filenames produced by the profiler.</tt></dd></dl>
111 <dl><dt><a name="Browser-StopTracing"><strong>StopTracing</strong></a>(self)</dt><dd><tt>Stops tracing and returns the result as TimelineData <a href="__builtin__.html#object">object</a>.</tt></dd></dl>
113 <dl><dt><a name="Browser-__enter__"><strong>__enter__</strong></a>(self)</dt></dl>
115 <dl><dt><a name="Browser-__exit__"><strong>__exit__</strong></a>(self, *args)</dt></dl>
117 <dl><dt><a name="Browser-__init__"><strong>__init__</strong></a>(self, backend, platform_backend)</dt></dl>
119 <dl><dt><a name="Browser-is_profiler_active"><strong>is_profiler_active</strong></a>(self, profiler_name)</dt></dl>
122 Data descriptors defined here:<br>
123 <dl><dt><strong>__dict__</strong></dt>
124 <dd><tt>dictionary for instance variables (if defined)</tt></dd>
126 <dl><dt><strong>__weakref__</strong></dt>
127 <dd><tt>list of weak references to the object (if defined)</tt></dd>
129 <dl><dt><strong>browser_type</strong></dt>
131 <dl><dt><strong>cpu_stats</strong></dt>
132 <dd><tt>Returns a dict of cpu statistics for the system.<br>
133 { 'Browser': {<br>
134 'CpuProcessTime': S,<br>
135 'TotalTime': T<br>
137 'Gpu': {<br>
138 'CpuProcessTime': S,<br>
139 'TotalTime': T<br>
141 'Renderer': {<br>
142 'CpuProcessTime': S,<br>
143 'TotalTime': T<br>
146 Any of the above keys may be missing on a per-platform basis.</tt></dd>
148 <dl><dt><strong>extensions</strong></dt>
150 <dl><dt><strong>foreground_tab</strong></dt>
152 <dl><dt><strong>http_server</strong></dt>
154 <dl><dt><strong>io_stats</strong></dt>
155 <dd><tt>Returns a dict of IO statistics for the browser:<br>
156 { 'Browser': {<br>
157 'ReadOperationCount': W,<br>
158 'WriteOperationCount': X,<br>
159 'ReadTransferCount': Y,<br>
160 'WriteTransferCount': Z<br>
162 'Gpu': {<br>
163 'ReadOperationCount': W,<br>
164 'WriteOperationCount': X,<br>
165 'ReadTransferCount': Y,<br>
166 'WriteTransferCount': Z<br>
168 'Renderer': {<br>
169 'ReadOperationCount': W,<br>
170 'WriteOperationCount': X,<br>
171 'ReadTransferCount': Y,<br>
172 'WriteTransferCount': Z<br>
176 <dl><dt><strong>is_content_shell</strong></dt>
177 <dd><tt>Returns whether this browser is a content shell, only.</tt></dd>
179 <dl><dt><strong>is_tracing_running</strong></dt>
181 <dl><dt><strong>local_servers</strong></dt>
182 <dd><tt>Returns the currently running local servers.</tt></dd>
184 <dl><dt><strong>memory_stats</strong></dt>
185 <dd><tt>Returns a dict of memory statistics for the browser:<br>
186 { 'Browser': {<br>
187 'VM': R,<br>
188 'VMPeak': S,<br>
189 'WorkingSetSize': T,<br>
190 'WorkingSetSizePeak': U,<br>
191 'ProportionalSetSize': V,<br>
192 'PrivateDirty': W<br>
194 'Gpu': {<br>
195 'VM': R,<br>
196 'VMPeak': S,<br>
197 'WorkingSetSize': T,<br>
198 'WorkingSetSizePeak': U,<br>
199 'ProportionalSetSize': V,<br>
200 'PrivateDirty': W<br>
202 'Renderer': {<br>
203 'VM': R,<br>
204 'VMPeak': S,<br>
205 'WorkingSetSize': T,<br>
206 'WorkingSetSizePeak': U,<br>
207 'ProportionalSetSize': V,<br>
208 'PrivateDirty': W<br>
210 'SystemCommitCharge': X,<br>
211 'SystemTotalPhysicalMemory': Y,<br>
212 'ProcessCount': Z,<br>
214 Any of the above keys may be missing on a per-platform basis.</tt></dd>
216 <dl><dt><strong>platform</strong></dt>
218 <dl><dt><strong>supports_extensions</strong></dt>
220 <dl><dt><strong>supports_system_info</strong></dt>
222 <dl><dt><strong>supports_tab_control</strong></dt>
224 <dl><dt><strong>supports_tracing</strong></dt>
226 <dl><dt><strong>synthetic_gesture_source_type</strong></dt>
228 <dl><dt><strong>tabs</strong></dt>
230 </td></tr></table> <p>
231 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
232 <tr bgcolor="#ffc8d8">
233 <td colspan=3 valign=bottom> <br>
234 <font color="#000000" face="helvetica, arial"><a name="BrowserFinderOptions">class <strong>BrowserFinderOptions</strong></a>(<a href="optparse.html#Values">optparse.Values</a>)</font></td></tr>
236 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
237 <td colspan=2><tt>Options to be used for discovering a browser.<br> </tt></td></tr>
239 <td width="100%">Methods defined here:<br>
240 <dl><dt><a name="BrowserFinderOptions-AppendExtraBrowserArgs"><strong>AppendExtraBrowserArgs</strong></a>(self, args)</dt></dl>
242 <dl><dt><a name="BrowserFinderOptions-Copy"><strong>Copy</strong></a>(self)</dt></dl>
244 <dl><dt><a name="BrowserFinderOptions-CreateParser"><strong>CreateParser</strong></a>(self, *args, **kwargs)</dt></dl>
246 <dl><dt><a name="BrowserFinderOptions-MergeDefaultValues"><strong>MergeDefaultValues</strong></a>(self, defaults)</dt></dl>
248 <dl><dt><a name="BrowserFinderOptions-__init__"><strong>__init__</strong></a>(self, browser_type<font color="#909090">=None</font>)</dt></dl>
251 Methods inherited from <a href="optparse.html#Values">optparse.Values</a>:<br>
252 <dl><dt><a name="BrowserFinderOptions-__cmp__"><strong>__cmp__</strong></a>(self, other)</dt></dl>
254 <dl><dt><a name="BrowserFinderOptions-__repr__"><strong>__repr__</strong></a> = _repr(self)</dt></dl>
256 <dl><dt><a name="BrowserFinderOptions-__str__"><strong>__str__</strong></a>(self)</dt></dl>
258 <dl><dt><a name="BrowserFinderOptions-ensure_value"><strong>ensure_value</strong></a>(self, attr, value)</dt></dl>
260 <dl><dt><a name="BrowserFinderOptions-read_file"><strong>read_file</strong></a>(self, filename, mode<font color="#909090">='careful'</font>)</dt></dl>
262 <dl><dt><a name="BrowserFinderOptions-read_module"><strong>read_module</strong></a>(self, modname, mode<font color="#909090">='careful'</font>)</dt></dl>
264 </td></tr></table> <p>
265 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
266 <tr bgcolor="#ffc8d8">
267 <td colspan=3 valign=bottom> <br>
268 <font color="#000000" face="helvetica, arial"><a name="PageMeasurement">class <strong>PageMeasurement</strong></a>(<a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a>)</font></td></tr>
270 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
271 <td colspan=2><tt>Glue code for running a measurement across a set of pages.<br>
273 To use this, subclass from the measurement and override MeasurePage. For<br>
276 class BodyChildElementMeasurement(<a href="#PageMeasurement">PageMeasurement</a>):<br>
277 def <a href="#PageMeasurement-MeasurePage">MeasurePage</a>(self, page, tab, results):<br>
278 body_child_count = tab.EvaluateJavaScript(<br>
279 'document.body.children.length')<br>
280 results.Add('body_children', 'count', body_child_count)<br>
282 if __name__ == '__main__':<br>
283 page_measurement.Main(BodyChildElementMeasurement())<br>
285 To add test-specific options:<br>
287 class BodyChildElementMeasurement(<a href="#PageMeasurement">PageMeasurement</a>):<br>
288 def <a href="#PageMeasurement-AddCommandLineArgs">AddCommandLineArgs</a>(parser):<br>
289 parser.add_option('--element', action='store', default='body')<br>
291 def <a href="#PageMeasurement-MeasurePage">MeasurePage</a>(self, page, tab, results):<br>
292 body_child_count = tab.EvaluateJavaScript(<br>
293 'document.querySelector('%s').children.length')<br>
294 results.Add('children', 'count', child_count)<br> </tt></td></tr>
296 <td width="100%"><dl><dt>Method resolution order:</dt>
297 <dd><a href="telemetry.page.page_measurement.html#PageMeasurement">PageMeasurement</a></dd>
298 <dd><a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a></dd>
299 <dd><a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a></dd>
300 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
303 Methods defined here:<br>
304 <dl><dt><a name="PageMeasurement-MeasurePage"><strong>MeasurePage</strong></a>(self, page, tab, results)</dt><dd><tt>Override to actually measure the page's performance.<br>
306 page is a page_set.Page<br>
307 tab is an instance of telemetry.core.<a href="#Tab">Tab</a><br>
309 Should call results.Add(name, units, value) for each result, or raise an<br>
310 exception on failure. The name and units of each Add() call must be<br>
311 the same across all iterations. The name 'url' must not be used.<br>
313 Prefer field names that are in accordance with python variable style. E.g.<br>
316 Put together:<br>
318 def <a href="#PageMeasurement-MeasurePage">MeasurePage</a>(self, page, tab, results):<br>
319 res = tab.EvaluateJavaScript('2+2')<br>
320 if res != 4:<br>
321 raise Exception('Oh, wow.')<br>
322 results.Add('two_plus_two', 'count', res)</tt></dd></dl>
324 <dl><dt><a name="PageMeasurement-__init__"><strong>__init__</strong></a>(self, action_name_to_run<font color="#909090">=''</font>, needs_browser_restart_after_each_page<font color="#909090">=False</font>, discard_first_result<font color="#909090">=False</font>, clear_cache_before_each_run<font color="#909090">=False</font>)</dt></dl>
327 Data descriptors defined here:<br>
328 <dl><dt><strong>results_are_the_same_on_every_page</strong></dt>
329 <dd><tt>By default, measurements are assumed to output the same values for every<br>
330 page. This allows incremental output, for example in CSV. If, however, the<br>
331 measurement discovers what values it can report as it goes, and those values<br>
332 may vary from page to page, you need to override this function and return<br>
333 False. Output will not appear in this mode until the entire pageset has<br>
337 Methods inherited from <a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a>:<br>
338 <dl><dt><a name="PageMeasurement-CanRunForPage"><strong>CanRunForPage</strong></a>(self, page)</dt><dd><tt>Override to customize if the test can be ran for the given page.</tt></dd></dl>
340 <dl><dt><a name="PageMeasurement-CleanUpAfterPage"><strong>CleanUpAfterPage</strong></a>(self, page, tab)</dt><dd><tt>Called after the test run method was run, even if it failed.</tt></dd></dl>
342 <dl><dt><a name="PageMeasurement-CreateExpectations"><strong>CreateExpectations</strong></a>(self, page_set)</dt><dd><tt>Override to make this test generate its own expectations instead of<br>
343 any that may have been defined in the page set.</tt></dd></dl>
345 <dl><dt><a name="PageMeasurement-CreatePageSet"><strong>CreatePageSet</strong></a>(self, args, options)</dt><dd><tt>Override to make this test generate its own page set instead of<br>
346 allowing arbitrary page sets entered from the command-line.</tt></dd></dl>
348 <dl><dt><a name="PageMeasurement-CustomizeBrowserOptions"><strong>CustomizeBrowserOptions</strong></a>(self, options)</dt><dd><tt>Override to add test-specific options to the BrowserOptions <a href="__builtin__.html#object">object</a></tt></dd></dl>
350 <dl><dt><a name="PageMeasurement-CustomizeBrowserOptionsForPageSet"><strong>CustomizeBrowserOptionsForPageSet</strong></a>(self, page_set, options)</dt><dd><tt>Set options required for this page set.<br>
352 These options will be used every time the browser is started while running<br>
353 this page set. They may, however, be further modified by<br>
354 CustomizeBrowserOptionsForSinglePage or by the profiler.</tt></dd></dl>
356 <dl><dt><a name="PageMeasurement-CustomizeBrowserOptionsForSinglePage"><strong>CustomizeBrowserOptionsForSinglePage</strong></a>(self, page, options)</dt><dd><tt>Set options specific to the test and the given page.<br>
358 This will be called with the current page when the browser is (re)started.<br>
359 Changing options at this point only makes sense if the browser is being<br>
360 restarted for each page. Note that if page has a startup_url, the browser<br>
361 will always be restarted for each run.</tt></dd></dl>
363 <dl><dt><a name="PageMeasurement-DidNavigateToPage"><strong>DidNavigateToPage</strong></a>(self, page, tab)</dt><dd><tt>Override to do operations right after the page is navigated and after<br>
364 all waiting for completion has occurred.</tt></dd></dl>
366 <dl><dt><a name="PageMeasurement-DidRunAction"><strong>DidRunAction</strong></a>(self, page, tab, action)</dt><dd><tt>Override to do operations after running the action on the page.</tt></dd></dl>
368 <dl><dt><a name="PageMeasurement-DidRunActions"><strong>DidRunActions</strong></a>(self, page, tab)</dt><dd><tt>Override to do operations after running the actions on the page.</tt></dd></dl>
370 <dl><dt><a name="PageMeasurement-DidRunPageRepeats"><strong>DidRunPageRepeats</strong></a>(self, page)</dt><dd><tt>Override to do operations after each page is iterated over.</tt></dd></dl>
372 <dl><dt><a name="PageMeasurement-DidRunTest"><strong>DidRunTest</strong></a>(self, browser, results)</dt><dd><tt>Override to do operations after all page set(s) are completed.<br>
374 This will occur before the browser is torn down.</tt></dd></dl>
376 <dl><dt><a name="PageMeasurement-DidStartBrowser"><strong>DidStartBrowser</strong></a>(self, browser)</dt><dd><tt>Override to customize the browser right after it has launched.</tt></dd></dl>
378 <dl><dt><a name="PageMeasurement-DidStartHTTPServer"><strong>DidStartHTTPServer</strong></a>(self, tab)</dt><dd><tt>Override to do operations after the HTTP server is started.</tt></dd></dl>
380 <dl><dt><a name="PageMeasurement-IsExiting"><strong>IsExiting</strong></a>(self)</dt></dl>
382 <dl><dt><a name="PageMeasurement-RequestExit"><strong>RequestExit</strong></a>(self)</dt></dl>
384 <dl><dt><a name="PageMeasurement-RestartBrowserBeforeEachPage"><strong>RestartBrowserBeforeEachPage</strong></a>(self)</dt><dd><tt>Should the browser be restarted for the page?<br>
386 This returns true if the test needs to unconditionally restart the<br>
387 browser for each page. It may be called before the browser is started.</tt></dd></dl>
389 <dl><dt><a name="PageMeasurement-Run"><strong>Run</strong></a>(self, page, tab, results)</dt></dl>
391 <dl><dt><a name="PageMeasurement-RunNavigateSteps"><strong>RunNavigateSteps</strong></a>(self, page, tab)</dt><dd><tt>Navigates the tab to the page URL attribute.<br>
393 Runs the 'navigate_steps' page attribute as a compound action.</tt></dd></dl>
395 <dl><dt><a name="PageMeasurement-StopBrowserAfterPage"><strong>StopBrowserAfterPage</strong></a>(self, browser, page)</dt><dd><tt>Should the browser be stopped after the page is run?<br>
397 This is called after a page is run to decide whether the browser needs to<br>
398 be stopped to clean up its state. If it is stopped, then it will be<br>
399 restarted to run the next page.<br>
401 A test that overrides this can look at both the page and the browser to<br>
402 decide whether it needs to stop the browser.</tt></dd></dl>
404 <dl><dt><a name="PageMeasurement-TabForPage"><strong>TabForPage</strong></a>(self, page, browser)</dt><dd><tt>Override to select a different tab for the page. For instance, to<br>
405 create a new tab for every page, return browser.tabs.New().</tt></dd></dl>
407 <dl><dt><a name="PageMeasurement-ValidatePageSet"><strong>ValidatePageSet</strong></a>(self, page_set)</dt><dd><tt>Override to examine the page set before the test run. Useful for<br>
408 example to validate that the pageset can be used with the test.</tt></dd></dl>
410 <dl><dt><a name="PageMeasurement-WillNavigateToPage"><strong>WillNavigateToPage</strong></a>(self, page, tab)</dt><dd><tt>Override to do operations before the page is navigated, notably Telemetry<br>
411 will already have performed the following operations on the browser before<br>
412 calling this function:<br>
413 * Ensure only one tab is open.<br>
414 * Call WaitForDocumentReadyStateToComplete on the tab.</tt></dd></dl>
416 <dl><dt><a name="PageMeasurement-WillRunAction"><strong>WillRunAction</strong></a>(self, page, tab, action)</dt><dd><tt>Override to do operations before running the action on the page.</tt></dd></dl>
418 <dl><dt><a name="PageMeasurement-WillRunActions"><strong>WillRunActions</strong></a>(self, page, tab)</dt><dd><tt>Override to do operations before running the actions on the page.</tt></dd></dl>
420 <dl><dt><a name="PageMeasurement-WillRunPageRepeats"><strong>WillRunPageRepeats</strong></a>(self, page)</dt><dd><tt>Override to do operations before each page is iterated over.</tt></dd></dl>
422 <dl><dt><a name="PageMeasurement-WillRunTest"><strong>WillRunTest</strong></a>(self, options)</dt><dd><tt>Override to do operations before the page set(s) are navigated.</tt></dd></dl>
424 <dl><dt><a name="PageMeasurement-WillStartBrowser"><strong>WillStartBrowser</strong></a>(self, browser)</dt><dd><tt>Override to manipulate the browser environment before it launches.</tt></dd></dl>
427 Data descriptors inherited from <a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a>:<br>
428 <dl><dt><strong>action_name_to_run</strong></dt>
430 <dl><dt><strong>attempts</strong></dt>
431 <dd><tt>Maximum number of times test will be attempted.</tt></dd>
433 <dl><dt><strong>clear_cache_before_each_run</strong></dt>
434 <dd><tt>When set to True, the browser's disk and memory cache will be cleared<br>
435 before each run.</tt></dd>
437 <dl><dt><strong>close_tabs_before_run</strong></dt>
438 <dd><tt>When set to True, all tabs are closed before running the test for the<br>
439 first time.</tt></dd>
441 <dl><dt><strong>discard_first_result</strong></dt>
442 <dd><tt>When set to True, the first run of the test is discarded. This is<br>
443 useful for cases where it's desirable to have some test resource cached so<br>
444 the first run of the test can warm things up.</tt></dd>
446 <dl><dt><strong>max_errors</strong></dt>
447 <dd><tt>Maximum number of errors allowed for the page set.</tt></dd>
449 <dl><dt><strong>max_failures</strong></dt>
450 <dd><tt>Maximum number of failures allowed for the page set.</tt></dd>
453 Class methods inherited from <a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a>:<br>
454 <dl><dt><a name="PageMeasurement-AddCommandLineArgs"><strong>AddCommandLineArgs</strong></a>(cls, parser)<font color="#909090"><font face="helvetica, arial"> from <a href="__builtin__.html#type">__builtin__.type</a></font></font></dt><dd><tt>Override to accept custom command-line arguments.</tt></dd></dl>
456 <dl><dt><a name="PageMeasurement-ProcessCommandLineArgs"><strong>ProcessCommandLineArgs</strong></a>(cls, parser, args)<font color="#909090"><font face="helvetica, arial"> from <a href="__builtin__.html#type">__builtin__.type</a></font></font></dt><dd><tt>Override to process command-line arguments.<br>
458 We pass in parser so we can call parser.error().</tt></dd></dl>
461 Data descriptors inherited from <a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a>:<br>
462 <dl><dt><strong>__dict__</strong></dt>
463 <dd><tt>dictionary for instance variables (if defined)</tt></dd>
465 <dl><dt><strong>__weakref__</strong></dt>
466 <dd><tt>list of weak references to the object (if defined)</tt></dd>
468 </td></tr></table> <p>
469 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
470 <tr bgcolor="#ffc8d8">
471 <td colspan=3 valign=bottom> <br>
472 <font color="#000000" face="helvetica, arial"><a name="Tab">class <strong>Tab</strong></a>(<a href="telemetry.core.web_contents.html#WebContents">telemetry.core.web_contents.WebContents</a>)</font></td></tr>
474 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
475 <td colspan=2><tt>Represents a tab in the browser<br>
477 The important parts of the <a href="#Tab">Tab</a> <a href="__builtin__.html#object">object</a> are in the runtime and page objects.<br>
479 # Navigates the tab to a given url.<br>
480 tab.<a href="#Tab-Navigate">Navigate</a>('<a href="http://www.google.com/">http://www.google.com/</a>')<br>
482 # Evaluates 1+1 in the tab's JavaScript context.<br>
483 tab.Evaluate('1+1')<br> </tt></td></tr>
485 <td width="100%"><dl><dt>Method resolution order:</dt>
486 <dd><a href="telemetry.core.tab.html#Tab">Tab</a></dd>
487 <dd><a href="telemetry.core.web_contents.html#WebContents">telemetry.core.web_contents.WebContents</a></dd>
488 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
491 Methods defined here:<br>
492 <dl><dt><a name="Tab-Activate"><strong>Activate</strong></a>(self)</dt><dd><tt>Brings this tab to the foreground asynchronously.<br>
494 Not all browsers or browser versions support this method.<br>
495 Be sure to check browser.supports_tab_control.<br>
497 Please note: this is asynchronous. There is a delay between this call<br>
498 and the page's documentVisibilityState becoming 'visible', and yet more<br>
499 delay until the actual tab is visible to the user. None of these delays<br>
500 are included in this call.</tt></dd></dl>
502 <dl><dt><a name="Tab-ClearCache"><strong>ClearCache</strong></a>(self, force)</dt><dd><tt>Clears the browser's networking related disk, memory and other caches.<br>
505 force: Iff true, navigates to about:blank which destroys the previous<br>
506 renderer, ensuring that even "live" resources in the memory cache are<br>
507 cleared.</tt></dd></dl>
509 <dl><dt><a name="Tab-ClearHighlight"><strong>ClearHighlight</strong></a>(self, color)</dt><dd><tt>Clears a highlight of the given bitmap.RgbaColor.</tt></dd></dl>
511 <dl><dt><a name="Tab-CollectGarbage"><strong>CollectGarbage</strong></a>(self)</dt></dl>
513 <dl><dt><a name="Tab-GetCookieByName"><strong>GetCookieByName</strong></a>(self, name, timeout<font color="#909090">=60</font>)</dt><dd><tt>Returns the value of the cookie by the given |name|.</tt></dd></dl>
515 <dl><dt><a name="Tab-Highlight"><strong>Highlight</strong></a>(self, color)</dt><dd><tt>Synchronously highlights entire tab contents with the given RgbaColor.<br>
517 TODO(tonyg): It is possible that the z-index hack here might not work for<br>
518 all pages. If this happens, DevTools also provides a method for this.</tt></dd></dl>
520 <dl><dt><a name="Tab-Navigate"><strong>Navigate</strong></a>(self, url, script_to_evaluate_on_commit<font color="#909090">=None</font>, timeout<font color="#909090">=60</font>)</dt><dd><tt>Navigates to url.<br>
522 If |script_to_evaluate_on_commit| is given, the script source string will be<br>
523 evaluated when the navigation is committed. This is after the context of<br>
524 the page exists, but before any script on the page itself has executed.</tt></dd></dl>
526 <dl><dt><a name="Tab-PerformActionAndWaitForNavigate"><strong>PerformActionAndWaitForNavigate</strong></a>(self, action_function, timeout<font color="#909090">=60</font>)</dt><dd><tt>Executes action_function, and waits for the navigation to complete.<br>
528 action_function must be a Python function that results in a navigation.<br>
529 This function returns when the navigation is complete or when<br>
530 the timeout has been exceeded.</tt></dd></dl>
532 <dl><dt><a name="Tab-Screenshot"><strong>Screenshot</strong></a>(self, timeout<font color="#909090">=60</font>)</dt><dd><tt>Capture a screenshot of the tab's contents.<br>
535 A telemetry.core.Bitmap.</tt></dd></dl>
537 <dl><dt><a name="Tab-StartVideoCapture"><strong>StartVideoCapture</strong></a>(self, min_bitrate_mbps)</dt><dd><tt>Starts capturing video of the tab's contents.<br>
539 This works by flashing the entire tab contents to a arbitrary color and then<br>
540 starting video recording. When the frames are processed, we can look for<br>
541 that flash as the content bounds.<br>
544 min_bitrate_mbps: The minimum caputre bitrate in MegaBits Per Second.<br>
545 The platform is free to deliver a higher bitrate if it can do so<br>
546 without increasing overhead.</tt></dd></dl>
548 <dl><dt><a name="Tab-StopVideoCapture"><strong>StopVideoCapture</strong></a>(self)</dt><dd><tt>Stops recording video of the tab's contents.<br>
550 This looks for the initial color flash in the first frame to establish the<br>
551 tab content boundaries and then omits all frames displaying the flash.<br>
554 (time_ms, bitmap) tuples representing each video keyframe. Only the first<br>
555 frame in a run of sequential duplicate bitmaps is typically included.<br>
556 time_ms is milliseconds since navigationStart.<br>
557 bitmap is a telemetry.core.Bitmap.</tt></dd></dl>
559 <dl><dt><a name="Tab-__init__"><strong>__init__</strong></a>(self, inspector_backend)</dt></dl>
562 Data descriptors defined here:<br>
563 <dl><dt><strong>browser</strong></dt>
564 <dd><tt>The browser in which this tab resides.</tt></dd>
566 <dl><dt><strong>dom_stats</strong></dt>
567 <dd><tt>A dictionary populated with measured DOM statistics.<br>
569 Currently this dictionary contains:<br>
571 'document_count': integer,<br>
572 'node_count': integer,<br>
573 'event_listener_count': integer<br>
576 <dl><dt><strong>is_video_capture_running</strong></dt>
578 <dl><dt><strong>screenshot_supported</strong></dt>
579 <dd><tt>True if the browser instance is capable of capturing screenshots.</tt></dd>
581 <dl><dt><strong>url</strong></dt>
583 <dl><dt><strong>video_capture_supported</strong></dt>
584 <dd><tt>True if the browser instance is capable of capturing video.</tt></dd>
587 Methods inherited from <a href="telemetry.core.web_contents.html#WebContents">telemetry.core.web_contents.WebContents</a>:<br>
588 <dl><dt><a name="Tab-Close"><strong>Close</strong></a>(self)</dt><dd><tt>Closes this page.<br>
590 Not all browsers or browser versions support this method.<br>
591 Be sure to check browser.supports_tab_control.</tt></dd></dl>
593 <dl><dt><a name="Tab-EvaluateJavaScript"><strong>EvaluateJavaScript</strong></a>(self, expr, timeout<font color="#909090">=90</font>)</dt><dd><tt>Evalutes expr in JavaScript and returns the JSONized result.<br>
595 Consider using ExecuteJavaScript for cases where the result of the<br>
596 expression is not needed.<br>
598 If evaluation throws in JavaScript, a Python EvaluateException will<br>
601 If the result of the evaluation cannot be JSONized, then an<br>
602 EvaluationException will be raised.</tt></dd></dl>
604 <dl><dt><a name="Tab-EvaluateJavaScriptInContext"><strong>EvaluateJavaScriptInContext</strong></a>(self, expr, context_id, timeout<font color="#909090">=90</font>)</dt><dd><tt>Similar to ExecuteJavaScript, except context_id can refer to an iframe.<br>
605 The main page has context_id=1, the first iframe context_id=2, etc.</tt></dd></dl>
607 <dl><dt><a name="Tab-ExecuteJavaScript"><strong>ExecuteJavaScript</strong></a>(self, expr, timeout<font color="#909090">=90</font>)</dt><dd><tt>Executes expr in JavaScript. Does not return the result.<br>
609 If the expression failed to evaluate, EvaluateException will be raised.</tt></dd></dl>
611 <dl><dt><a name="Tab-ExecuteJavaScriptInContext"><strong>ExecuteJavaScriptInContext</strong></a>(self, expr, context_id, timeout<font color="#909090">=90</font>)</dt><dd><tt>Similar to ExecuteJavaScript, except context_id can refer to an iframe.<br>
612 The main page has context_id=1, the first iframe context_id=2, etc.</tt></dd></dl>
614 <dl><dt><a name="Tab-HasReachedQuiescence"><strong>HasReachedQuiescence</strong></a>(self)</dt><dd><tt>Determine whether the page has reached quiescence after loading.<br>
617 True if 2 seconds have passed since last resource received, false<br>
618 otherwise.</tt></dd></dl>
620 <dl><dt><a name="Tab-StartTimelineRecording"><strong>StartTimelineRecording</strong></a>(self, options<font color="#909090">=None</font>)</dt></dl>
622 <dl><dt><a name="Tab-StopTimelineRecording"><strong>StopTimelineRecording</strong></a>(self)</dt></dl>
624 <dl><dt><a name="Tab-TakeJSHeapSnapshot"><strong>TakeJSHeapSnapshot</strong></a>(self, timeout<font color="#909090">=120</font>)</dt></dl>
626 <dl><dt><a name="Tab-WaitForDocumentReadyStateToBeComplete"><strong>WaitForDocumentReadyStateToBeComplete</strong></a>(self, timeout<font color="#909090">=90</font>)</dt></dl>
628 <dl><dt><a name="Tab-WaitForDocumentReadyStateToBeInteractiveOrBetter"><strong>WaitForDocumentReadyStateToBeInteractiveOrBetter</strong></a>(self, timeout<font color="#909090">=90</font>)</dt></dl>
630 <dl><dt><a name="Tab-WaitForJavaScriptExpression"><strong>WaitForJavaScriptExpression</strong></a>(self, expr, timeout)</dt><dd><tt>Waits for the given JavaScript expression to be True.<br>
632 This method is robust against any given Evaluation timing out.</tt></dd></dl>
635 Data descriptors inherited from <a href="telemetry.core.web_contents.html#WebContents">telemetry.core.web_contents.WebContents</a>:<br>
636 <dl><dt><strong>__dict__</strong></dt>
637 <dd><tt>dictionary for instance variables (if defined)</tt></dd>
639 <dl><dt><strong>__weakref__</strong></dt>
640 <dd><tt>list of weak references to the object (if defined)</tt></dd>
642 <dl><dt><strong>is_timeline_recording_running</strong></dt>
644 <dl><dt><strong>message_output_stream</strong></dt>
646 <dl><dt><strong>timeline_model</strong></dt>
648 </td></tr></table></td></tr></table><p>
649 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
650 <tr bgcolor="#eeaa77">
651 <td colspan=3 valign=bottom> <br>
652 <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
654 <tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td>
655 <td width="100%"><dl><dt><a name="-RunPage"><strong>RunPage</strong></a> = Run(test, page_set, expectations, finder_options)</dt><dd><tt>Runs a given test against a given page_set with the given options.</tt></dd></dl>
656 </td></tr></table><p>
657 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
658 <tr bgcolor="#55aa55">
659 <td colspan=3 valign=bottom> <br>
660 <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
662 <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
663 <td width="100%"><strong>__all__</strong> = ['Browser', 'BrowserFinderOptions', 'PageMeasurement', 'RunPage', 'Tab']</td></tr></table>