1 2<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 3<html><head><title>Python: package telemetry</title> 4</head><body bgcolor="#f0f0f8"> 5 6<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading"> 7<tr bgcolor="#7799ee"> 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> 13<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> 18 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> 35 36<tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td> 37<td width="100%"><dl> 38<dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a> 39</font></dt><dd> 40<dl> 41<dt><font face="helvetica, arial"><a href="telemetry.core.browser.html#Browser">telemetry.core.browser.Browser</a> 42</font></dt></dl> 43</dd> 44<dt><font face="helvetica, arial"><a href="optparse.html#Values">optparse.Values</a> 45</font></dt><dd> 46<dl> 47<dt><font face="helvetica, arial"><a href="telemetry.core.browser_options.html#BrowserFinderOptions">telemetry.core.browser_options.BrowserFinderOptions</a> 48</font></dt></dl> 49</dd> 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>) 51</font></dt><dd> 52<dl> 53<dt><font face="helvetica, arial"><a href="telemetry.core.tab.html#Tab">telemetry.core.tab.Tab</a> 54</font></dt></dl> 55</dd> 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>) 57</font></dt><dd> 58<dl> 59<dt><font face="helvetica, arial"><a href="telemetry.page.page_measurement.html#PageMeasurement">telemetry.page.page_measurement.PageMeasurement</a> 60</font></dt></dl> 61</dd> 62</dl> 63 <p> 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> 68 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> 71 <br> 72To create a browser instance, use browser_finder.FindBrowser.<br> 73 <br> 74Be sure to clean up after yourself by calling <a href="#Browser-Close">Close</a>() when you are done with<br> 75the 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> 79<tr><td> </td> 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> 82 83<dl><dt><a name="Browser-GetStackTrace"><strong>GetStackTrace</strong></a>(self)</dt></dl> 84 85<dl><dt><a name="Browser-GetStandardOutput"><strong>GetStandardOutput</strong></a>(self)</dt></dl> 86 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> 88 <br> 89See the documentation of the SystemInfo class for more details.</tt></dd></dl> 90 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> 92 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> 94 95<dl><dt><a name="Browser-Start"><strong>Start</strong></a>(self)</dt></dl> 96 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> 98 <br> 99It will be closed when the browser closes.</tt></dd></dl> 100 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> 103 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> 105 106<dl><dt><a name="Browser-StopProfiling"><strong>StopProfiling</strong></a>(self)</dt><dd><tt>Stops all active profilers and saves their results.<br> 107 <br> 108Returns:<br> 109 A list of filenames produced by the profiler.</tt></dd></dl> 110 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> 112 113<dl><dt><a name="Browser-__enter__"><strong>__enter__</strong></a>(self)</dt></dl> 114 115<dl><dt><a name="Browser-__exit__"><strong>__exit__</strong></a>(self, *args)</dt></dl> 116 117<dl><dt><a name="Browser-__init__"><strong>__init__</strong></a>(self, backend, platform_backend)</dt></dl> 118 119<dl><dt><a name="Browser-is_profiler_active"><strong>is_profiler_active</strong></a>(self, profiler_name)</dt></dl> 120 121<hr> 122Data descriptors defined here:<br> 123<dl><dt><strong>__dict__</strong></dt> 124<dd><tt>dictionary for instance variables (if defined)</tt></dd> 125</dl> 126<dl><dt><strong>__weakref__</strong></dt> 127<dd><tt>list of weak references to the object (if defined)</tt></dd> 128</dl> 129<dl><dt><strong>browser_type</strong></dt> 130</dl> 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> 136 },<br> 137 'Gpu': {<br> 138 'CpuProcessTime': S,<br> 139 'TotalTime': T<br> 140 },<br> 141 'Renderer': {<br> 142 'CpuProcessTime': S,<br> 143 'TotalTime': T<br> 144 }<br> 145}<br> 146Any of the above keys may be missing on a per-platform basis.</tt></dd> 147</dl> 148<dl><dt><strong>extensions</strong></dt> 149</dl> 150<dl><dt><strong>foreground_tab</strong></dt> 151</dl> 152<dl><dt><strong>http_server</strong></dt> 153</dl> 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> 161 },<br> 162 'Gpu': {<br> 163 'ReadOperationCount': W,<br> 164 'WriteOperationCount': X,<br> 165 'ReadTransferCount': Y,<br> 166 'WriteTransferCount': Z<br> 167 },<br> 168 'Renderer': {<br> 169 'ReadOperationCount': W,<br> 170 'WriteOperationCount': X,<br> 171 'ReadTransferCount': Y,<br> 172 'WriteTransferCount': Z<br> 173 }<br> 174}</tt></dd> 175</dl> 176<dl><dt><strong>is_content_shell</strong></dt> 177<dd><tt>Returns whether this browser is a content shell, only.</tt></dd> 178</dl> 179<dl><dt><strong>is_tracing_running</strong></dt> 180</dl> 181<dl><dt><strong>local_servers</strong></dt> 182<dd><tt>Returns the currently running local servers.</tt></dd> 183</dl> 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> 193 },<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> 201 },<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> 209 },<br> 210 'SystemCommitCharge': X,<br> 211 'SystemTotalPhysicalMemory': Y,<br> 212 'ProcessCount': Z,<br> 213}<br> 214Any of the above keys may be missing on a per-platform basis.</tt></dd> 215</dl> 216<dl><dt><strong>platform</strong></dt> 217</dl> 218<dl><dt><strong>supports_extensions</strong></dt> 219</dl> 220<dl><dt><strong>supports_system_info</strong></dt> 221</dl> 222<dl><dt><strong>supports_tab_control</strong></dt> 223</dl> 224<dl><dt><strong>supports_tracing</strong></dt> 225</dl> 226<dl><dt><strong>synthetic_gesture_source_type</strong></dt> 227</dl> 228<dl><dt><strong>tabs</strong></dt> 229</dl> 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> 235 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> 238<tr><td> </td> 239<td width="100%">Methods defined here:<br> 240<dl><dt><a name="BrowserFinderOptions-AppendExtraBrowserArgs"><strong>AppendExtraBrowserArgs</strong></a>(self, args)</dt></dl> 241 242<dl><dt><a name="BrowserFinderOptions-Copy"><strong>Copy</strong></a>(self)</dt></dl> 243 244<dl><dt><a name="BrowserFinderOptions-CreateParser"><strong>CreateParser</strong></a>(self, *args, **kwargs)</dt></dl> 245 246<dl><dt><a name="BrowserFinderOptions-MergeDefaultValues"><strong>MergeDefaultValues</strong></a>(self, defaults)</dt></dl> 247 248<dl><dt><a name="BrowserFinderOptions-__init__"><strong>__init__</strong></a>(self, browser_type<font color="#909090">=None</font>)</dt></dl> 249 250<hr> 251Methods 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> 253 254<dl><dt><a name="BrowserFinderOptions-__repr__"><strong>__repr__</strong></a> = _repr(self)</dt></dl> 255 256<dl><dt><a name="BrowserFinderOptions-__str__"><strong>__str__</strong></a>(self)</dt></dl> 257 258<dl><dt><a name="BrowserFinderOptions-ensure_value"><strong>ensure_value</strong></a>(self, attr, value)</dt></dl> 259 260<dl><dt><a name="BrowserFinderOptions-read_file"><strong>read_file</strong></a>(self, filename, mode<font color="#909090">='careful'</font>)</dt></dl> 261 262<dl><dt><a name="BrowserFinderOptions-read_module"><strong>read_module</strong></a>(self, modname, mode<font color="#909090">='careful'</font>)</dt></dl> 263 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> 269 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> 272 <br> 273To use this, subclass from the measurement and override MeasurePage. For<br> 274example:<br> 275 <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> 281 <br> 282 if __name__ == '__main__':<br> 283 page_measurement.Main(BodyChildElementMeasurement())<br> 284 <br> 285To add test-specific options:<br> 286 <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> 290 <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> 295<tr><td> </td> 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> 301</dl> 302<hr> 303Methods 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> 305 <br> 306page is a page_set.Page<br> 307tab is an instance of telemetry.core.<a href="#Tab">Tab</a><br> 308 <br> 309Should call results.Add(name, units, value) for each result, or raise an<br> 310exception on failure. The name and units of each Add() call must be<br> 311the same across all iterations. The name 'url' must not be used.<br> 312 <br> 313Prefer field names that are in accordance with python variable style. E.g.<br> 314field_name.<br> 315 <br> 316Put together:<br> 317 <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> 323 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> 325 326<hr> 327Data 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> 330page. This allows incremental output, for example in CSV. If, however, the<br> 331measurement discovers what values it can report as it goes, and those values<br> 332may vary from page to page, you need to override this function and return<br> 333False. Output will not appear in this mode until the entire pageset has<br> 334run.</tt></dd> 335</dl> 336<hr> 337Methods 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> 339 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> 341 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> 343any that may have been defined in the page set.</tt></dd></dl> 344 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> 346allowing arbitrary page sets entered from the command-line.</tt></dd></dl> 347 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> 349 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> 351 <br> 352These options will be used every time the browser is started while running<br> 353this page set. They may, however, be further modified by<br> 354CustomizeBrowserOptionsForSinglePage or by the profiler.</tt></dd></dl> 355 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> 357 <br> 358This will be called with the current page when the browser is (re)started.<br> 359Changing options at this point only makes sense if the browser is being<br> 360restarted for each page. Note that if page has a startup_url, the browser<br> 361will always be restarted for each run.</tt></dd></dl> 362 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> 364all waiting for completion has occurred.</tt></dd></dl> 365 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> 367 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> 369 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> 371 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> 373 <br> 374This will occur before the browser is torn down.</tt></dd></dl> 375 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> 377 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> 379 380<dl><dt><a name="PageMeasurement-IsExiting"><strong>IsExiting</strong></a>(self)</dt></dl> 381 382<dl><dt><a name="PageMeasurement-RequestExit"><strong>RequestExit</strong></a>(self)</dt></dl> 383 384<dl><dt><a name="PageMeasurement-RestartBrowserBeforeEachPage"><strong>RestartBrowserBeforeEachPage</strong></a>(self)</dt><dd><tt>Should the browser be restarted for the page?<br> 385 <br> 386This returns true if the test needs to unconditionally restart the<br> 387browser for each page. It may be called before the browser is started.</tt></dd></dl> 388 389<dl><dt><a name="PageMeasurement-Run"><strong>Run</strong></a>(self, page, tab, results)</dt></dl> 390 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> 392 <br> 393Runs the 'navigate_steps' page attribute as a compound action.</tt></dd></dl> 394 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> 396 <br> 397This is called after a page is run to decide whether the browser needs to<br> 398be stopped to clean up its state. If it is stopped, then it will be<br> 399restarted to run the next page.<br> 400 <br> 401A test that overrides this can look at both the page and the browser to<br> 402decide whether it needs to stop the browser.</tt></dd></dl> 403 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> 405create a new tab for every page, return browser.tabs.New().</tt></dd></dl> 406 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> 408example to validate that the pageset can be used with the test.</tt></dd></dl> 409 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> 411will already have performed the following operations on the browser before<br> 412calling this function:<br> 413* Ensure only one tab is open.<br> 414* Call WaitForDocumentReadyStateToComplete on the tab.</tt></dd></dl> 415 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> 417 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> 419 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> 421 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> 423 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> 425 426<hr> 427Data 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> 429</dl> 430<dl><dt><strong>attempts</strong></dt> 431<dd><tt>Maximum number of times test will be attempted.</tt></dd> 432</dl> 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> 435before each run.</tt></dd> 436</dl> 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> 439first time.</tt></dd> 440</dl> 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> 443useful for cases where it's desirable to have some test resource cached so<br> 444the first run of the test can warm things up.</tt></dd> 445</dl> 446<dl><dt><strong>max_errors</strong></dt> 447<dd><tt>Maximum number of errors allowed for the page set.</tt></dd> 448</dl> 449<dl><dt><strong>max_failures</strong></dt> 450<dd><tt>Maximum number of failures allowed for the page set.</tt></dd> 451</dl> 452<hr> 453Class 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> 455 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> 457 <br> 458We pass in parser so we can call parser.error().</tt></dd></dl> 459 460<hr> 461Data 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> 464</dl> 465<dl><dt><strong>__weakref__</strong></dt> 466<dd><tt>list of weak references to the object (if defined)</tt></dd> 467</dl> 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> 473 474<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> 475<td colspan=2><tt>Represents a tab in the browser<br> 476 <br> 477The important parts of the <a href="#Tab">Tab</a> <a href="__builtin__.html#object">object</a> are in the runtime and page objects.<br> 478E.g.:<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> 481 <br> 482 # Evaluates 1+1 in the tab's JavaScript context.<br> 483 tab.Evaluate('1+1')<br> </tt></td></tr> 484<tr><td> </td> 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> 489</dl> 490<hr> 491Methods 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> 493 <br> 494Not all browsers or browser versions support this method.<br> 495Be sure to check browser.supports_tab_control.<br> 496 <br> 497Please note: this is asynchronous. There is a delay between this call<br> 498and the page's documentVisibilityState becoming 'visible', and yet more<br> 499delay until the actual tab is visible to the user. None of these delays<br> 500are included in this call.</tt></dd></dl> 501 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> 503 <br> 504Args:<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> 508 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> 510 511<dl><dt><a name="Tab-CollectGarbage"><strong>CollectGarbage</strong></a>(self)</dt></dl> 512 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> 514 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> 516 <br> 517TODO(tonyg): It is possible that the z-index hack here might not work for<br> 518all pages. If this happens, DevTools also provides a method for this.</tt></dd></dl> 519 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> 521 <br> 522If |script_to_evaluate_on_commit| is given, the script source string will be<br> 523evaluated when the navigation is committed. This is after the context of<br> 524the page exists, but before any script on the page itself has executed.</tt></dd></dl> 525 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> 527 <br> 528action_function must be a Python function that results in a navigation.<br> 529This function returns when the navigation is complete or when<br> 530the timeout has been exceeded.</tt></dd></dl> 531 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> 533 <br> 534Returns:<br> 535 A telemetry.core.Bitmap.</tt></dd></dl> 536 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> 538 <br> 539This works by flashing the entire tab contents to a arbitrary color and then<br> 540starting video recording. When the frames are processed, we can look for<br> 541that flash as the content bounds.<br> 542 <br> 543Args:<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> 547 548<dl><dt><a name="Tab-StopVideoCapture"><strong>StopVideoCapture</strong></a>(self)</dt><dd><tt>Stops recording video of the tab's contents.<br> 549 <br> 550This looks for the initial color flash in the first frame to establish the<br> 551tab content boundaries and then omits all frames displaying the flash.<br> 552 <br> 553Yields:<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> 558 559<dl><dt><a name="Tab-__init__"><strong>__init__</strong></a>(self, inspector_backend)</dt></dl> 560 561<hr> 562Data descriptors defined here:<br> 563<dl><dt><strong>browser</strong></dt> 564<dd><tt>The browser in which this tab resides.</tt></dd> 565</dl> 566<dl><dt><strong>dom_stats</strong></dt> 567<dd><tt>A dictionary populated with measured DOM statistics.<br> 568 <br> 569Currently this dictionary contains:<br> 570{<br> 571 'document_count': integer,<br> 572 'node_count': integer,<br> 573 'event_listener_count': integer<br> 574}</tt></dd> 575</dl> 576<dl><dt><strong>is_video_capture_running</strong></dt> 577</dl> 578<dl><dt><strong>screenshot_supported</strong></dt> 579<dd><tt>True if the browser instance is capable of capturing screenshots.</tt></dd> 580</dl> 581<dl><dt><strong>url</strong></dt> 582</dl> 583<dl><dt><strong>video_capture_supported</strong></dt> 584<dd><tt>True if the browser instance is capable of capturing video.</tt></dd> 585</dl> 586<hr> 587Methods 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> 589 <br> 590Not all browsers or browser versions support this method.<br> 591Be sure to check browser.supports_tab_control.</tt></dd></dl> 592 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> 594 <br> 595Consider using ExecuteJavaScript for cases where the result of the<br> 596expression is not needed.<br> 597 <br> 598If evaluation throws in JavaScript, a Python EvaluateException will<br> 599be raised.<br> 600 <br> 601If the result of the evaluation cannot be JSONized, then an<br> 602EvaluationException will be raised.</tt></dd></dl> 603 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> 605The main page has context_id=1, the first iframe context_id=2, etc.</tt></dd></dl> 606 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> 608 <br> 609If the expression failed to evaluate, EvaluateException will be raised.</tt></dd></dl> 610 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> 612The main page has context_id=1, the first iframe context_id=2, etc.</tt></dd></dl> 613 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> 615 <br> 616Returns:<br> 617 True if 2 seconds have passed since last resource received, false<br> 618 otherwise.</tt></dd></dl> 619 620<dl><dt><a name="Tab-StartTimelineRecording"><strong>StartTimelineRecording</strong></a>(self, options<font color="#909090">=None</font>)</dt></dl> 621 622<dl><dt><a name="Tab-StopTimelineRecording"><strong>StopTimelineRecording</strong></a>(self)</dt></dl> 623 624<dl><dt><a name="Tab-TakeJSHeapSnapshot"><strong>TakeJSHeapSnapshot</strong></a>(self, timeout<font color="#909090">=120</font>)</dt></dl> 625 626<dl><dt><a name="Tab-WaitForDocumentReadyStateToBeComplete"><strong>WaitForDocumentReadyStateToBeComplete</strong></a>(self, timeout<font color="#909090">=90</font>)</dt></dl> 627 628<dl><dt><a name="Tab-WaitForDocumentReadyStateToBeInteractiveOrBetter"><strong>WaitForDocumentReadyStateToBeInteractiveOrBetter</strong></a>(self, timeout<font color="#909090">=90</font>)</dt></dl> 629 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> 631 <br> 632This method is robust against any given Evaluation timing out.</tt></dd></dl> 633 634<hr> 635Data 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> 638</dl> 639<dl><dt><strong>__weakref__</strong></dt> 640<dd><tt>list of weak references to the object (if defined)</tt></dd> 641</dl> 642<dl><dt><strong>is_timeline_recording_running</strong></dt> 643</dl> 644<dl><dt><strong>message_output_stream</strong></dt> 645</dl> 646<dl><dt><strong>timeline_model</strong></dt> 647</dl> 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> 653 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> 661 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> 664</body></html>