1 2 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 3 <html><head><title>Python: module telemetry.page.page_measurement</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><a href="telemetry.html"><font color="#ffffff">telemetry</font></a>.<a href="telemetry.page.html"><font color="#ffffff">page</font></a>.page_measurement</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/page/page_measurement.py">telemetry/page/page_measurement.py</a></font></td></tr></table> 12 <p><tt># Copyright (c) 2012 The Chromium Authors. All rights reserved.<br> 13 # Use of this source code is governed by a BSD-style license that can be<br> 14 # found in the LICENSE file.</tt></p> 15 <p> 16 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 17 <tr bgcolor="#aa55cc"> 18 <td colspan=3 valign=bottom> <br> 19 <font color="#ffffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr> 20 21 <tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td> 22 <td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="telemetry.page.page_test.html">telemetry.page.page_test</a><br> 23 </td><td width="25%" valign=top></td><td width="25%" valign=top></td><td width="25%" valign=top></td></tr></table></td></tr></table><p> 24 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 25 <tr bgcolor="#ee77aa"> 26 <td colspan=3 valign=bottom> <br> 27 <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr> 28 29 <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td> 30 <td width="100%"><dl> 31 <dt><font face="helvetica, arial"><a href="telemetry.page.page_test.html#Failure">telemetry.page.page_test.Failure</a>(<a href="exceptions.html#Exception">exceptions.Exception</a>) 32 </font></dt><dd> 33 <dl> 34 <dt><font face="helvetica, arial"><a href="telemetry.page.page_measurement.html#MeasurementFailure">MeasurementFailure</a> 35 </font></dt></dl> 36 </dd> 37 <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>) 38 </font></dt><dd> 39 <dl> 40 <dt><font face="helvetica, arial"><a href="telemetry.page.page_measurement.html#PageMeasurement">PageMeasurement</a> 41 </font></dt></dl> 42 </dd> 43 </dl> 44 <p> 45 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 46 <tr bgcolor="#ffc8d8"> 47 <td colspan=3 valign=bottom> <br> 48 <font color="#000000" face="helvetica, arial"><a name="MeasurementFailure">class <strong>MeasurementFailure</strong></a>(<a href="telemetry.page.page_test.html#Failure">telemetry.page.page_test.Failure</a>)</font></td></tr> 49 50 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> 51 <td colspan=2><tt>Exception that can be thrown from MeasurePage to indicate an undesired but<br> 52 designed-for problem.<br> </tt></td></tr> 53 <tr><td> </td> 54 <td width="100%"><dl><dt>Method resolution order:</dt> 55 <dd><a href="telemetry.page.page_measurement.html#MeasurementFailure">MeasurementFailure</a></dd> 56 <dd><a href="telemetry.page.page_test.html#Failure">telemetry.page.page_test.Failure</a></dd> 57 <dd><a href="exceptions.html#Exception">exceptions.Exception</a></dd> 58 <dd><a href="exceptions.html#BaseException">exceptions.BaseException</a></dd> 59 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd> 60 </dl> 61 <hr> 62 Data descriptors inherited from <a href="telemetry.page.page_test.html#Failure">telemetry.page.page_test.Failure</a>:<br> 63 <dl><dt><strong>__weakref__</strong></dt> 64 <dd><tt>list of weak references to the object (if defined)</tt></dd> 65 </dl> 66 <hr> 67 Methods inherited from <a href="exceptions.html#Exception">exceptions.Exception</a>:<br> 68 <dl><dt><a name="MeasurementFailure-__init__"><strong>__init__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__init__">__init__</a>(...) initializes x; see help(type(x)) for signature</tt></dd></dl> 69 70 <hr> 71 Data and other attributes inherited from <a href="exceptions.html#Exception">exceptions.Exception</a>:<br> 72 <dl><dt><strong>__new__</strong> = <built-in method __new__ of type object><dd><tt>T.<a href="#MeasurementFailure-__new__">__new__</a>(S, ...) -> a new object with type S, a subtype of T</tt></dl> 73 74 <hr> 75 Methods inherited from <a href="exceptions.html#BaseException">exceptions.BaseException</a>:<br> 76 <dl><dt><a name="MeasurementFailure-__delattr__"><strong>__delattr__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__delattr__">__delattr__</a>('name') <==> del x.name</tt></dd></dl> 77 78 <dl><dt><a name="MeasurementFailure-__getattribute__"><strong>__getattribute__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__getattribute__">__getattribute__</a>('name') <==> x.name</tt></dd></dl> 79 80 <dl><dt><a name="MeasurementFailure-__getitem__"><strong>__getitem__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__getitem__">__getitem__</a>(y) <==> x[y]</tt></dd></dl> 81 82 <dl><dt><a name="MeasurementFailure-__getslice__"><strong>__getslice__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__getslice__">__getslice__</a>(i, j) <==> x[i:j]<br> 83 <br> 84 Use of negative indices is not supported.</tt></dd></dl> 85 86 <dl><dt><a name="MeasurementFailure-__reduce__"><strong>__reduce__</strong></a>(...)</dt></dl> 87 88 <dl><dt><a name="MeasurementFailure-__repr__"><strong>__repr__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__repr__">__repr__</a>() <==> repr(x)</tt></dd></dl> 89 90 <dl><dt><a name="MeasurementFailure-__setattr__"><strong>__setattr__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__setattr__">__setattr__</a>('name', value) <==> x.name = value</tt></dd></dl> 91 92 <dl><dt><a name="MeasurementFailure-__setstate__"><strong>__setstate__</strong></a>(...)</dt></dl> 93 94 <dl><dt><a name="MeasurementFailure-__str__"><strong>__str__</strong></a>(...)</dt><dd><tt>x.<a href="#MeasurementFailure-__str__">__str__</a>() <==> str(x)</tt></dd></dl> 95 96 <dl><dt><a name="MeasurementFailure-__unicode__"><strong>__unicode__</strong></a>(...)</dt></dl> 97 98 <hr> 99 Data descriptors inherited from <a href="exceptions.html#BaseException">exceptions.BaseException</a>:<br> 100 <dl><dt><strong>__dict__</strong></dt> 101 </dl> 102 <dl><dt><strong>args</strong></dt> 103 </dl> 104 <dl><dt><strong>message</strong></dt> 105 </dl> 106 </td></tr></table> <p> 107 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 108 <tr bgcolor="#ffc8d8"> 109 <td colspan=3 valign=bottom> <br> 110 <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> 111 112 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> 113 <td colspan=2><tt>Glue code for running a measurement across a set of pages.<br> 114 <br> 115 To use this, subclass from the measurement and override MeasurePage. For<br> 116 example:<br> 117 <br> 118 class BodyChildElementMeasurement(<a href="#PageMeasurement">PageMeasurement</a>):<br> 119 def <a href="#PageMeasurement-MeasurePage">MeasurePage</a>(self, page, tab, results):<br> 120 body_child_count = tab.EvaluateJavaScript(<br> 121 'document.body.children.length')<br> 122 results.Add('body_children', 'count', body_child_count)<br> 123 <br> 124 if __name__ == '__main__':<br> 125 page_measurement.Main(BodyChildElementMeasurement())<br> 126 <br> 127 To add test-specific options:<br> 128 <br> 129 class BodyChildElementMeasurement(<a href="#PageMeasurement">PageMeasurement</a>):<br> 130 def <a href="#PageMeasurement-AddCommandLineArgs">AddCommandLineArgs</a>(parser):<br> 131 parser.add_option('--element', action='store', default='body')<br> 132 <br> 133 def <a href="#PageMeasurement-MeasurePage">MeasurePage</a>(self, page, tab, results):<br> 134 body_child_count = tab.EvaluateJavaScript(<br> 135 'document.querySelector('%s').children.length')<br> 136 results.Add('children', 'count', child_count)<br> </tt></td></tr> 137 <tr><td> </td> 138 <td width="100%"><dl><dt>Method resolution order:</dt> 139 <dd><a href="telemetry.page.page_measurement.html#PageMeasurement">PageMeasurement</a></dd> 140 <dd><a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a></dd> 141 <dd><a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a></dd> 142 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd> 143 </dl> 144 <hr> 145 Methods defined here:<br> 146 <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> 147 <br> 148 page is a page_set.Page<br> 149 tab is an instance of telemetry.core.Tab<br> 150 <br> 151 Should call results.Add(name, units, value) for each result, or raise an<br> 152 exception on failure. The name and units of each Add() call must be<br> 153 the same across all iterations. The name 'url' must not be used.<br> 154 <br> 155 Prefer field names that are in accordance with python variable style. E.g.<br> 156 field_name.<br> 157 <br> 158 Put together:<br> 159 <br> 160 def <a href="#PageMeasurement-MeasurePage">MeasurePage</a>(self, page, tab, results):<br> 161 res = tab.EvaluateJavaScript('2+2')<br> 162 if res != 4:<br> 163 raise Exception('Oh, wow.')<br> 164 results.Add('two_plus_two', 'count', res)</tt></dd></dl> 165 166 <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> 167 168 <hr> 169 Data descriptors defined here:<br> 170 <dl><dt><strong>results_are_the_same_on_every_page</strong></dt> 171 <dd><tt>By default, measurements are assumed to output the same values for every<br> 172 page. This allows incremental output, for example in CSV. If, however, the<br> 173 measurement discovers what values it can report as it goes, and those values<br> 174 may vary from page to page, you need to override this function and return<br> 175 False. Output will not appear in this mode until the entire pageset has<br> 176 run.</tt></dd> 177 </dl> 178 <hr> 179 Methods inherited from <a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a>:<br> 180 <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> 181 182 <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> 183 184 <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> 185 any that may have been defined in the page set.</tt></dd></dl> 186 187 <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> 188 allowing arbitrary page sets entered from the command-line.</tt></dd></dl> 189 190 <dl><dt><a name="PageMeasurement-CustomizeBrowserOptions"><strong>CustomizeBrowserOptions</strong></a>(self, options)</dt><dd><tt>Override to add test-specific options to the BrowserOptions object</tt></dd></dl> 191 192 <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> 193 <br> 194 These options will be used every time the browser is started while running<br> 195 this page set. They may, however, be further modified by<br> 196 CustomizeBrowserOptionsForSinglePage or by the profiler.</tt></dd></dl> 197 198 <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> 199 <br> 200 This will be called with the current page when the browser is (re)started.<br> 201 Changing options at this point only makes sense if the browser is being<br> 202 restarted for each page. Note that if page has a startup_url, the browser<br> 203 will always be restarted for each run.</tt></dd></dl> 204 205 <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> 206 all waiting for completion has occurred.</tt></dd></dl> 207 208 <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> 209 210 <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> 211 212 <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> 213 214 <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> 215 <br> 216 This will occur before the browser is torn down.</tt></dd></dl> 217 218 <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> 219 220 <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> 221 222 <dl><dt><a name="PageMeasurement-IsExiting"><strong>IsExiting</strong></a>(self)</dt></dl> 223 224 <dl><dt><a name="PageMeasurement-RequestExit"><strong>RequestExit</strong></a>(self)</dt></dl> 225 226 <dl><dt><a name="PageMeasurement-RestartBrowserBeforeEachPage"><strong>RestartBrowserBeforeEachPage</strong></a>(self)</dt><dd><tt>Should the browser be restarted for the page?<br> 227 <br> 228 This returns true if the test needs to unconditionally restart the<br> 229 browser for each page. It may be called before the browser is started.</tt></dd></dl> 230 231 <dl><dt><a name="PageMeasurement-Run"><strong>Run</strong></a>(self, page, tab, results)</dt></dl> 232 233 <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> 234 <br> 235 Runs the 'navigate_steps' page attribute as a compound action.</tt></dd></dl> 236 237 <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> 238 <br> 239 This is called after a page is run to decide whether the browser needs to<br> 240 be stopped to clean up its state. If it is stopped, then it will be<br> 241 restarted to run the next page.<br> 242 <br> 243 A test that overrides this can look at both the page and the browser to<br> 244 decide whether it needs to stop the browser.</tt></dd></dl> 245 246 <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> 247 create a new tab for every page, return browser.tabs.New().</tt></dd></dl> 248 249 <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> 250 example to validate that the pageset can be used with the test.</tt></dd></dl> 251 252 <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> 253 will already have performed the following operations on the browser before<br> 254 calling this function:<br> 255 * Ensure only one tab is open.<br> 256 * Call WaitForDocumentReadyStateToComplete on the tab.</tt></dd></dl> 257 258 <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> 259 260 <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> 261 262 <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> 263 264 <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> 265 266 <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> 267 268 <hr> 269 Data descriptors inherited from <a href="telemetry.page.page_test.html#PageTest">telemetry.page.page_test.PageTest</a>:<br> 270 <dl><dt><strong>action_name_to_run</strong></dt> 271 </dl> 272 <dl><dt><strong>attempts</strong></dt> 273 <dd><tt>Maximum number of times test will be attempted.</tt></dd> 274 </dl> 275 <dl><dt><strong>clear_cache_before_each_run</strong></dt> 276 <dd><tt>When set to True, the browser's disk and memory cache will be cleared<br> 277 before each run.</tt></dd> 278 </dl> 279 <dl><dt><strong>close_tabs_before_run</strong></dt> 280 <dd><tt>When set to True, all tabs are closed before running the test for the<br> 281 first time.</tt></dd> 282 </dl> 283 <dl><dt><strong>discard_first_result</strong></dt> 284 <dd><tt>When set to True, the first run of the test is discarded. This is<br> 285 useful for cases where it's desirable to have some test resource cached so<br> 286 the first run of the test can warm things up.</tt></dd> 287 </dl> 288 <dl><dt><strong>max_errors</strong></dt> 289 <dd><tt>Maximum number of errors allowed for the page set.</tt></dd> 290 </dl> 291 <dl><dt><strong>max_failures</strong></dt> 292 <dd><tt>Maximum number of failures allowed for the page set.</tt></dd> 293 </dl> 294 <hr> 295 Class methods inherited from <a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a>:<br> 296 <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> 297 298 <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> 299 <br> 300 We pass in parser so we can call parser.error().</tt></dd></dl> 301 302 <hr> 303 Data descriptors inherited from <a href="telemetry.core.command_line.html#ArgumentHandlerMixIn">telemetry.core.command_line.ArgumentHandlerMixIn</a>:<br> 304 <dl><dt><strong>__dict__</strong></dt> 305 <dd><tt>dictionary for instance variables (if defined)</tt></dd> 306 </dl> 307 <dl><dt><strong>__weakref__</strong></dt> 308 <dd><tt>list of weak references to the object (if defined)</tt></dd> 309 </dl> 310 </td></tr></table></td></tr></table> 311 </body></html>
