1 2 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 3 <html><head><title>Python: module telemetry.internal.browser.tab</title> 4 <meta charset="utf-8"> 5 </head><body bgcolor="#f0f0f8"> 6 7 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading"> 8 <tr bgcolor="#7799ee"> 9 <td valign=bottom> <br> 10 <font color="#ffffff" face="helvetica, arial"> <br><big><big><strong><a href="telemetry.html"><font color="#ffffff">telemetry</font></a>.<a href="telemetry.internal.html"><font color="#ffffff">internal</font></a>.<a href="telemetry.internal.browser.html"><font color="#ffffff">browser</font></a>.tab</strong></big></big></font></td 11 ><td align=right valign=bottom 12 ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="../telemetry/internal/browser/tab.py">telemetry/internal/browser/tab.py</a></font></td></tr></table> 13 <p><tt># Copyright 2012 The Chromium Authors. All rights reserved.<br> 14 # Use of this source code is governed by a BSD-style license that can be<br> 15 # found in the LICENSE file.</tt></p> 16 <p> 17 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 18 <tr bgcolor="#aa55cc"> 19 <td colspan=3 valign=bottom> <br> 20 <font color="#ffffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr> 21 22 <tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td> 23 <td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="telemetry.internal.image_processing.video.html">telemetry.internal.image_processing.video</a><br> 24 </td><td width="25%" valign=top><a href="telemetry.internal.browser.web_contents.html">telemetry.internal.browser.web_contents</a><br> 25 </td><td width="25%" valign=top></td><td width="25%" valign=top></td></tr></table></td></tr></table><p> 26 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 27 <tr bgcolor="#ee77aa"> 28 <td colspan=3 valign=bottom> <br> 29 <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr> 30 31 <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td> 32 <td width="100%"><dl> 33 <dt><font face="helvetica, arial"><a href="telemetry.internal.browser.web_contents.html#WebContents">telemetry.internal.browser.web_contents.WebContents</a>(<a href="__builtin__.html#object">__builtin__.object</a>) 34 </font></dt><dd> 35 <dl> 36 <dt><font face="helvetica, arial"><a href="telemetry.internal.browser.tab.html#Tab">Tab</a> 37 </font></dt></dl> 38 </dd> 39 </dl> 40 <p> 41 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 42 <tr bgcolor="#ffc8d8"> 43 <td colspan=3 valign=bottom> <br> 44 <font color="#000000" face="helvetica, arial"><a name="Tab">class <strong>Tab</strong></a>(<a href="telemetry.internal.browser.web_contents.html#WebContents">telemetry.internal.browser.web_contents.WebContents</a>)</font></td></tr> 45 46 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> 47 <td colspan=2><tt>Represents a tab in the browser<br> 48 <br> 49 The important parts of the <a href="#Tab">Tab</a> object are in the runtime and page objects.<br> 50 E.g.:<br> 51 # Navigates the tab to a given url.<br> 52 tab.<a href="#Tab-Navigate">Navigate</a>('<a href="http://www.google.com/">http://www.google.com/</a>')<br> 53 <br> 54 # Evaluates 1+1 in the tab's JavaScript context.<br> 55 tab.Evaluate('1+1')<br> </tt></td></tr> 56 <tr><td> </td> 57 <td width="100%"><dl><dt>Method resolution order:</dt> 58 <dd><a href="telemetry.internal.browser.tab.html#Tab">Tab</a></dd> 59 <dd><a href="telemetry.internal.browser.web_contents.html#WebContents">telemetry.internal.browser.web_contents.WebContents</a></dd> 60 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd> 61 </dl> 62 <hr> 63 Methods defined here:<br> 64 <dl><dt><a name="Tab-Activate"><strong>Activate</strong></a>(self)</dt><dd><tt>Brings this tab to the foreground asynchronously.<br> 65 <br> 66 Not all browsers or browser versions support this method.<br> 67 Be sure to check browser.supports_tab_control.<br> 68 <br> 69 Please note: this is asynchronous. There is a delay between this call<br> 70 and the page's documentVisibilityState becoming 'visible', and yet more<br> 71 delay until the actual tab is visible to the user. None of these delays<br> 72 are included in this call.<br> 73 <br> 74 Raises:<br> 75 devtools_http.DevToolsClientConnectionError<br> 76 devtools_client_backend.TabNotFoundError<br> 77 tab_list_backend.TabUnexpectedResponseException</tt></dd></dl> 78 79 <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> 80 <br> 81 Args:<br> 82 force: Iff true, navigates to about:blank which destroys the previous<br> 83 renderer, ensuring that even "live" resources in the memory cache are<br> 84 cleared.<br> 85 <br> 86 Raises:<br> 87 exceptions.EvaluateException<br> 88 exceptions.WebSocketDisconnected<br> 89 exceptions.TimeoutException<br> 90 exceptions.DevtoolsTargetCrashException<br> 91 errors.DeviceUnresponsiveError</tt></dd></dl> 92 93 <dl><dt><a name="Tab-ClearHighlight"><strong>ClearHighlight</strong></a>(self, color)</dt><dd><tt>Clears a highlight of the given bitmap.RgbaColor.<br> 94 <br> 95 Raises:<br> 96 exceptions.EvaluateException<br> 97 exceptions.WebSocketDisconnected<br> 98 exceptions.TimeoutException<br> 99 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 100 101 <dl><dt><a name="Tab-Close"><strong>Close</strong></a>(self)</dt><dd><tt>Closes this tab.<br> 102 <br> 103 Not all browsers or browser versions support this method.<br> 104 Be sure to check browser.supports_tab_control.<br> 105 <br> 106 Raises:<br> 107 devtools_http.DevToolsClientConnectionError<br> 108 devtools_client_backend.TabNotFoundError<br> 109 tab_list_backend.TabUnexpectedResponseException<br> 110 exceptions.TimeoutException</tt></dd></dl> 111 112 <dl><dt><a name="Tab-CollectGarbage"><strong>CollectGarbage</strong></a>(self)</dt><dd><tt>Forces a garbage collection.<br> 113 <br> 114 Raises:<br> 115 exceptions.WebSocketDisconnected<br> 116 exceptions.TimeoutException<br> 117 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 118 119 <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|.<br> 120 <br> 121 Raises:<br> 122 exceptions.WebSocketDisconnected<br> 123 exceptions.TimeoutException<br> 124 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 125 126 <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> 127 <br> 128 TODO(tonyg): It is possible that the z-index hack here might not work for<br> 129 all pages. If this happens, DevTools also provides a method for this.<br> 130 <br> 131 Raises:<br> 132 exceptions.EvaluateException<br> 133 exceptions.WebSocketDisconnected<br> 134 exceptions.TimeoutException<br> 135 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 136 137 <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> 138 <br> 139 Returns:<br> 140 A telemetry.core.Bitmap.<br> 141 Raises:<br> 142 exceptions.WebSocketDisconnected<br> 143 exceptions.TimeoutException<br> 144 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 145 146 <dl><dt><a name="Tab-StartVideoCapture"><strong>StartVideoCapture</strong></a>(self, min_bitrate_mbps, highlight_bitmap<font color="#909090">=RgbaColor(r=222, g=100, b=13, a=255)</font>)</dt><dd><tt>Starts capturing video of the tab's contents.<br> 147 <br> 148 This works by flashing the entire tab contents to a arbitrary color and then<br> 149 starting video recording. When the frames are processed, we can look for<br> 150 that flash as the content bounds.<br> 151 <br> 152 Args:<br> 153 min_bitrate_mbps: The minimum caputre bitrate in MegaBits Per Second.<br> 154 The platform is free to deliver a higher bitrate if it can do so<br> 155 without increasing overhead.<br> 156 <br> 157 Raises:<br> 158 exceptions.EvaluateException<br> 159 exceptions.WebSocketDisconnected<br> 160 exceptions.TimeoutException<br> 161 exceptions.DevtoolsTargetCrashException<br> 162 ValueError: If the required |min_bitrate_mbps| can't be achieved.</tt></dd></dl> 163 164 <dl><dt><a name="Tab-StopVideoCapture"><strong>StopVideoCapture</strong></a>(self)</dt><dd><tt>Stops recording video of the tab's contents.<br> 165 <br> 166 This looks for the initial color flash in the first frame to establish the<br> 167 tab content boundaries and then omits all frames displaying the flash.<br> 168 <br> 169 Returns:<br> 170 video: A video object which is a telemetry.core.Video</tt></dd></dl> 171 172 <dl><dt><a name="Tab-__init__"><strong>__init__</strong></a>(self, inspector_backend, tab_list_backend, browser)</dt></dl> 173 174 <hr> 175 Data descriptors defined here:<br> 176 <dl><dt><strong>browser</strong></dt> 177 <dd><tt>The browser in which this tab resides.</tt></dd> 178 </dl> 179 <dl><dt><strong>dom_stats</strong></dt> 180 <dd><tt>A dictionary populated with measured DOM statistics.<br> 181 <br> 182 Currently this dictionary contains:<br> 183 {<br> 184 'document_count': integer,<br> 185 'node_count': integer,<br> 186 'event_listener_count': integer<br> 187 }<br> 188 <br> 189 Raises:<br> 190 inspector_memory.InspectorMemoryException<br> 191 exceptions.TimeoutException<br> 192 exceptions.DevtoolsTargetCrashException</tt></dd> 193 </dl> 194 <dl><dt><strong>is_video_capture_running</strong></dt> 195 </dl> 196 <dl><dt><strong>screenshot_supported</strong></dt> 197 <dd><tt>True if the browser instance is capable of capturing screenshots.</tt></dd> 198 </dl> 199 <dl><dt><strong>url</strong></dt> 200 <dd><tt>Returns the URL of the tab, as reported by devtools.<br> 201 <br> 202 Raises:<br> 203 devtools_http.DevToolsClientConnectionError</tt></dd> 204 </dl> 205 <dl><dt><strong>video_capture_supported</strong></dt> 206 <dd><tt>True if the browser instance is capable of capturing video.</tt></dd> 207 </dl> 208 <hr> 209 Methods inherited from <a href="telemetry.internal.browser.web_contents.html#WebContents">telemetry.internal.browser.web_contents.WebContents</a>:<br> 210 <dl><dt><a name="Tab-CloseConnections"><strong>CloseConnections</strong></a>(self)</dt><dd><tt>Closes all TCP sockets held open by the browser.<br> 211 <br> 212 Raises:<br> 213 exceptions.DevtoolsTargetCrashException if the tab is not alive.</tt></dd></dl> 214 215 <dl><dt><a name="Tab-EnableAllContexts"><strong>EnableAllContexts</strong></a>(self)</dt><dd><tt>Enable all contexts in a page. Returns the number of available contexts.<br> 216 <br> 217 Raises:<br> 218 exceptions.WebSocketDisconnected<br> 219 exceptions.TimeoutException<br> 220 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 221 222 <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> 223 <br> 224 Consider using ExecuteJavaScript for cases where the result of the<br> 225 expression is not needed.<br> 226 <br> 227 If evaluation throws in JavaScript, a Python EvaluateException will<br> 228 be raised.<br> 229 <br> 230 If the result of the evaluation cannot be JSONized, then an<br> 231 EvaluationException will be raised.<br> 232 <br> 233 Raises:<br> 234 exceptions.Error: See <a href="#Tab-EvaluateJavaScriptInContext">EvaluateJavaScriptInContext</a>() for a detailed list<br> 235 of possible exceptions.</tt></dd></dl> 236 237 <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> 238 The main page has context_id=1, the first iframe context_id=2, etc.<br> 239 <br> 240 Raises:<br> 241 exceptions.EvaluateException<br> 242 exceptions.WebSocketDisconnected<br> 243 exceptions.TimeoutException<br> 244 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 245 246 <dl><dt><a name="Tab-ExecuteJavaScript"><strong>ExecuteJavaScript</strong></a>(self, statement, timeout<font color="#909090">=90</font>)</dt><dd><tt>Executes statement in JavaScript. Does not return the result.<br> 247 <br> 248 If the statement failed to evaluate, EvaluateException will be raised.<br> 249 <br> 250 Raises:<br> 251 exceptions.Error: See <a href="#Tab-ExecuteJavaScriptInContext">ExecuteJavaScriptInContext</a>() for a detailed list of<br> 252 possible exceptions.</tt></dd></dl> 253 254 <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> 255 The main page has context_id=1, the first iframe context_id=2, etc.<br> 256 <br> 257 Raises:<br> 258 exceptions.EvaluateException<br> 259 exceptions.WebSocketDisconnected<br> 260 exceptions.TimeoutException<br> 261 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 262 263 <dl><dt><a name="Tab-GetUrl"><strong>GetUrl</strong></a>(self)</dt><dd><tt>Returns the URL to which the <a href="telemetry.internal.browser.web_contents.html#WebContents">WebContents</a> is connected.<br> 264 <br> 265 Raises:<br> 266 exceptions.Error: If there is an error in inspector backend connection.</tt></dd></dl> 267 268 <dl><dt><a name="Tab-GetWebviewContexts"><strong>GetWebviewContexts</strong></a>(self)</dt><dd><tt>Returns a list of webview contexts within the current inspector backend.<br> 269 <br> 270 Returns:<br> 271 A list of <a href="telemetry.internal.browser.web_contents.html#WebContents">WebContents</a> objects representing the webview contexts.<br> 272 <br> 273 Raises:<br> 274 exceptions.Error: If there is an error in inspector backend connection.</tt></dd></dl> 275 276 <dl><dt><a name="Tab-HasReachedQuiescence"><strong>HasReachedQuiescence</strong></a>(self)</dt><dd><tt>Determine whether the page has reached quiescence after loading.<br> 277 <br> 278 Returns:<br> 279 True if 2 seconds have passed since last resource received, false<br> 280 otherwise.<br> 281 Raises:<br> 282 exceptions.Error: See <a href="#Tab-EvaluateJavaScript">EvaluateJavaScript</a>() for a detailed list of<br> 283 possible exceptions.</tt></dd></dl> 284 285 <dl><dt><a name="Tab-IsAlive"><strong>IsAlive</strong></a>(self)</dt><dd><tt>Whether the <a href="telemetry.internal.browser.web_contents.html#WebContents">WebContents</a> is still operating normally.<br> 286 <br> 287 Since <a href="telemetry.internal.browser.web_contents.html#WebContents">WebContents</a> function asynchronously, this method does not guarantee<br> 288 that the <a href="telemetry.internal.browser.web_contents.html#WebContents">WebContents</a> will still be alive at any point in the future.<br> 289 <br> 290 Returns:<br> 291 A boolean indicating whether the <a href="telemetry.internal.browser.web_contents.html#WebContents">WebContents</a> is opearting normally.</tt></dd></dl> 292 293 <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">=90</font>)</dt><dd><tt>Navigates to url.<br> 294 <br> 295 If |script_to_evaluate_on_commit| is given, the script source string will be<br> 296 evaluated when the navigation is committed. This is after the context of<br> 297 the page exists, but before any script on the page itself has executed.<br> 298 <br> 299 Raises:<br> 300 exceptions.TimeoutException<br> 301 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 302 303 <dl><dt><a name="Tab-StartTimelineRecording"><strong>StartTimelineRecording</strong></a>(self)</dt><dd><tt>Starts timeline recording.<br> 304 <br> 305 Raises:<br> 306 exceptions.TimeoutException<br> 307 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 308 309 <dl><dt><a name="Tab-StopTimelineRecording"><strong>StopTimelineRecording</strong></a>(self)</dt><dd><tt>Stops timeline recording.<br> 310 <br> 311 Raises:<br> 312 exceptions.TimeoutException<br> 313 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 314 315 <dl><dt><a name="Tab-SynthesizeScrollGesture"><strong>SynthesizeScrollGesture</strong></a>(self, x<font color="#909090">=100</font>, y<font color="#909090">=800</font>, xDistance<font color="#909090">=0</font>, yDistance<font color="#909090">=-500</font>, xOverscroll<font color="#909090">=None</font>, yOverscroll<font color="#909090">=None</font>, preventFling<font color="#909090">=True</font>, speed<font color="#909090">=None</font>, gestureSourceType<font color="#909090">=None</font>, repeatCount<font color="#909090">=None</font>, repeatDelayMs<font color="#909090">=None</font>, interactionMarkerName<font color="#909090">=None</font>)</dt><dd><tt>Runs an inspector command that causes a repeatable browser driven scroll.<br> 316 <br> 317 Args:<br> 318 x: X coordinate of the start of the gesture in CSS pixels.<br> 319 y: Y coordinate of the start of the gesture in CSS pixels.<br> 320 xDistance: Distance to scroll along the X axis (positive to scroll left).<br> 321 yDistance: Ddistance to scroll along the Y axis (positive to scroll up).<br> 322 xOverscroll: Number of additional pixels to scroll back along the X axis.<br> 323 xOverscroll: Number of additional pixels to scroll back along the Y axis.<br> 324 preventFling: Prevents a fling gesture.<br> 325 speed: Swipe speed in pixels per second.<br> 326 gestureSourceType: Which type of input events to be generated.<br> 327 repeatCount: Number of additional repeats beyond the first scroll.<br> 328 repeatDelayMs: Number of milliseconds delay between each repeat.<br> 329 interactionMarkerName: The name of the interaction markers to generate.<br> 330 <br> 331 Raises:<br> 332 exceptions.TimeoutException<br> 333 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 334 335 <dl><dt><a name="Tab-WaitForDocumentReadyStateToBeComplete"><strong>WaitForDocumentReadyStateToBeComplete</strong></a>(self, timeout<font color="#909090">=90</font>)</dt><dd><tt>Waits for the document to finish loading.<br> 336 <br> 337 Raises:<br> 338 exceptions.Error: See <a href="#Tab-WaitForJavaScriptExpression">WaitForJavaScriptExpression</a>() for a detailed list<br> 339 of possible exceptions.</tt></dd></dl> 340 341 <dl><dt><a name="Tab-WaitForDocumentReadyStateToBeInteractiveOrBetter"><strong>WaitForDocumentReadyStateToBeInteractiveOrBetter</strong></a>(self, timeout<font color="#909090">=90</font>)</dt><dd><tt>Waits for the document to be interactive.<br> 342 <br> 343 Raises:<br> 344 exceptions.Error: See <a href="#Tab-WaitForJavaScriptExpression">WaitForJavaScriptExpression</a>() for a detailed list<br> 345 of possible exceptions.</tt></dd></dl> 346 347 <dl><dt><a name="Tab-WaitForJavaScriptExpression"><strong>WaitForJavaScriptExpression</strong></a>(self, expr, timeout, dump_page_state_on_timeout<font color="#909090">=True</font>)</dt><dd><tt>Waits for the given JavaScript expression to be True.<br> 348 <br> 349 This method is robust against any given Evaluation timing out.<br> 350 <br> 351 Args:<br> 352 expr: The expression to evaluate.<br> 353 timeout: The number of seconds to wait for the expression to be True.<br> 354 dump_page_state_on_timeout: Whether to provide additional information on<br> 355 the page state if a TimeoutException is thrown.<br> 356 <br> 357 Raises:<br> 358 exceptions.TimeoutException: On a timeout.<br> 359 exceptions.Error: See <a href="#Tab-EvaluateJavaScript">EvaluateJavaScript</a>() for a detailed list of<br> 360 possible exceptions.</tt></dd></dl> 361 362 <dl><dt><a name="Tab-WaitForNavigate"><strong>WaitForNavigate</strong></a>(self, timeout<font color="#909090">=90</font>)</dt><dd><tt>Waits for the navigation to complete.<br> 363 <br> 364 The current page is expect to be in a navigation.<br> 365 This function returns when the navigation is complete or when<br> 366 the timeout has been exceeded.<br> 367 <br> 368 Raises:<br> 369 exceptions.TimeoutException<br> 370 exceptions.DevtoolsTargetCrashException</tt></dd></dl> 371 372 <hr> 373 Data descriptors inherited from <a href="telemetry.internal.browser.web_contents.html#WebContents">telemetry.internal.browser.web_contents.WebContents</a>:<br> 374 <dl><dt><strong>__dict__</strong></dt> 375 <dd><tt>dictionary for instance variables (if defined)</tt></dd> 376 </dl> 377 <dl><dt><strong>__weakref__</strong></dt> 378 <dd><tt>list of weak references to the object (if defined)</tt></dd> 379 </dl> 380 <dl><dt><strong>id</strong></dt> 381 <dd><tt>Return the unique id string for this tab object.</tt></dd> 382 </dl> 383 <dl><dt><strong>message_output_stream</strong></dt> 384 </dl> 385 <dl><dt><strong>timeline_model</strong></dt> 386 </dl> 387 </td></tr></table></td></tr></table><p> 388 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> 389 <tr bgcolor="#55aa55"> 390 <td colspan=3 valign=bottom> <br> 391 <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr> 392 393 <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td> 394 <td width="100%"><strong>DEFAULT_TAB_TIMEOUT</strong> = 60</td></tr></table> 395 </body></html>
