selenium-webdriver
Version:
The official WebDriver JavaScript bindings from the Selenium project
79 lines (74 loc) • 24.5 kB
HTML
<meta charset="UTF-8"><meta http-equiv="Content-Language" content="en" /><title>webdriver.promise</title><link href="dossier.css" rel="stylesheet" type="text/css"><div id="main-wrapper"><input type="checkbox" id="sidenav-toggle" /><main><header><h1>Namespace webdriver.promise</h1><a class="source" href="source/lib/webdriver/promise.js.src.html#l49">code »</a></header><section></section><section><h2>Classes</h2><div class="type-summary"><table><tbody><tr><td><dl><dt><a href="class_webdriver_promise_CanceledTaskError_.html">webdriver.promise.CanceledTaskError_</a><dd>Special error used to signal when a task is canceled because a previous
task in the same frame failed.<dt><a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a><dd>Handles the execution of scheduled tasks, each of which may be an
asynchronous operation.<dt><a href="class_webdriver_promise_Deferred.html">webdriver.promise.Deferred</a><dd>Represents a value that will be resolved at some point in the future.<dt><a href="class_webdriver_promise_Frame_.html">webdriver.promise.Frame_</a><dd>An execution frame within a <code class="type"><a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code>.<dt><a href="class_webdriver_promise_Node_.html">webdriver.promise.Node_</a><dd>A single node in an <code class="type"><a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code>'s task tree.<dt><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><dd>Represents the eventual value of a completed operation.<dt><a href="class_webdriver_promise_Task_.html">webdriver.promise.Task_</a><dd>A task to be executed by a <code class="type"><a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code>.</dl></table></div></section><div id="visibility-controls"><b>Show:</b><label for="show-public"><span><input type="checkbox" id="show-public" checked/></span>Public</label><label for="show-protected"><span><input type="checkbox" id="show-protected"/></span>Protected</label><label for="show-private"><span><input type="checkbox" id="show-private"/></span>Private</label></div><section id="static-functions"><h2>Global Functions</h2><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l751">code »</a><code class="type"><T></code> <span class="member"><a name="webdriver.promise.all">webdriver.promise.all</a> <span class="args">( arr )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Given an array of promises, will return a promise that will be fulfilled
with the fulfillment values of the input array's values. If any of the
input array's promises are rejected, the returned promise will be rejected
with the same reason.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>arr: <code class="type">!<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a></code><dd>An array of
promises to wait on.</dl><tr><th>Returns<tr><td><dl>A promise that is
fulfilled with an array containing the fulfilled values of the
input array, or rejected with the same reason as the first
rejected value.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l721">code »</a><span class="member"><a name="webdriver.promise.asap">webdriver.promise.asap</a> <span class="args">( value, callback, opt_errback )</span></span></div><p>Invokes the appropriate callback function as soon as a promised
<code >value</code> is resolved. This function is similar to
<code class="type"><a href="namespace_webdriver_promise.html#webdriver.promise.when">webdriver.promise.when</a></code>, except it does not return a new promise.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>value: <code class="type">*</code><dd>The value to observe.<dt>callback: <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function</a></code><dd>The function to call when the value is
resolved successfully.<dt>opt_errback: <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function</a>=</code><dd>The function to call when the value is
rejected.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l672">code »</a><span class="member"><a name="webdriver.promise.checkedNodeCall">webdriver.promise.checkedNodeCall</a> <span class="args">( fn )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Wraps a function that is assumed to be a node-style callback as its final
argument. This callback takes two arguments: an error value (which will be
null if the call succeeded), and the success value as the second argument.
If the call fails, the returned promise will be rejected, otherwise it will
be resolved with the result.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>fn: <code class="type">!<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function</a></code><dd>The function to wrap.</dl><tr><th>Returns<tr><td><dl>A promise that will be resolved with the
result of the provided function's callback.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2079">code »</a><span class="member"><a name="webdriver.promise.controlFlow">webdriver.promise.controlFlow</a> <span class="args">( )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code></span></div></summary><div class="info"><table><tbody><tr><th>Returns<tr><td><dl>The currently active control flow.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2110">code »</a><span class="member"><a name="webdriver.promise.createFlow">webdriver.promise.createFlow</a> <span class="args">( callback )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Creates a new control flow. The provided callback will be invoked as the
first task within the new flow, with the flow as its sole argument. Returns
a promise that resolves to the callback result.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>callback: <code class="type">function(!<a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a>)</code><dd>The entry point
to the newly created flow.</dl><tr><th>Returns<tr><td><dl>A promise that resolves to the callback
result.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l629">code »</a><span class="member"><a name="webdriver.promise.defer">webdriver.promise.defer</a> <span class="args">( opt_canceller )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Deferred.html">webdriver.promise.Deferred</a></code></span></div><p>Creates a new deferred object.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>opt_canceller: <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function</a>=</code><dd>Function to call when cancelling the
computation of this instance's value.</dl><tr><th>Returns<tr><td><dl>The new deferred object.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l612">code »</a><span class="member"><a name="webdriver.promise.delayed">webdriver.promise.delayed</a> <span class="args">( ms )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Creates a promise that will be resolved at a set time in the future.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>ms: <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code><dd>The amount of time, in milliseconds, to wait before
resolving the promise.</dl><tr><th>Returns<tr><td><dl>The promise.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l830">code »</a><code class="type"><TYPE, SELF></code> <span class="member"><a name="webdriver.promise.filter">webdriver.promise.filter</a> <span class="args">( arr, fn, opt_self )</span></span></div><p>Calls a function for each element in an array, and if the function returns
true adds the element to a new array.
<p>If the return value of the filter function is a promise, this function
will wait for it to be fulfilled before determining whether to insert the
element into the new array.
<p>If the filter function throws or returns a rejected promise, the promise
returned by this function will be rejected with the same reason. Only the
first failure will be reported; all subsequent errors will be silently
ignored.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>arr: <code class="type">!(<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a>.<TYPE>|<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a>)</code><dd>The
array to iterator over, or a promise that will resolve to said array.<dt>fn: <code class="type">function(this: SELF, TYPE, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, !<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a>.<TYPE>): (<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>|<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a>.<<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>>)</code><dd>The function
to call for each element in the array.<dt>opt_self: <code class="type">SELF=</code><dd>The object to be used as the value of 'this' within
<code >fn</code>.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l639">code »</a><span class="member"><a name="webdriver.promise.fulfilled">webdriver.promise.fulfilled</a> <span class="args">( opt_value )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Creates a promise that has been resolved with the given value.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>opt_value: <code class="type">*=</code><dd>The resolved value.</dl><tr><th>Returns<tr><td><dl>The resolved promise.</dl></table></div></details></div></div><div class="wrap-details private"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l916">code »</a><span class="member"><a name="webdriver.promise.fullyResolveKeys_">webdriver.promise.fullyResolveKeys_</a> <span class="args">( obj )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div></summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>obj: <code class="type">!(<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a>|<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code><dd>the object to resolve.</dl><tr><th>Returns<tr><td><dl>A promise that will be resolved with the
input object once all of its values have been fully resolved.</dl></table></div></details></div></div><div class="wrap-details private"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l877">code »</a><span class="member"><a name="webdriver.promise.fullyResolveValue_">webdriver.promise.fullyResolveValue_</a> <span class="args">( value )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div></summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>value: <code class="type">*</code><dd>The value to fully resolve. If a promise, assumed to
already be resolved.</dl><tr><th>Returns<tr><td><dl>A promise for a fully resolved version
of the input value.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l862">code »</a><span class="member"><a name="webdriver.promise.fullyResolved">webdriver.promise.fullyResolved</a> <span class="args">( value )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Returns a promise that will be resolved with the input value in a
fully-resolved state. If the value is an array, each element will be fully
resolved. Likewise, if the value is an object, all keys will be fully
resolved. In both cases, all nested arrays and objects will also be
fully resolved. All fields are resolved in place; the returned promise will
resolve on <code >value</code> and not a copy.
Warning: This function makes no checks against objects that contain
cyclical references:
<pre><code>
var value = {};
value['self'] = value;
webdriver.promise.fullyResolved(value); // Stack overflow.
</code></pre></summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>value: <code class="type">*</code><dd>The value to fully resolve.</dl><tr><th>Returns<tr><td><dl>A promise for a fully resolved version
of the input value.</dl></table></div></details></div></div><div class="wrap-details private"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l581">code »</a><span class="member"><a name="webdriver.promise.isError_">webdriver.promise.isError_</a> <span class="args">( value )</span> ⇒ <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code></span></div><p>Tests if a value is an Error-like object. This is more than an straight
instanceof check since the value may originate from another context.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>value: <code class="type">*</code><dd>The value to test.</dl><tr><th>Returns<tr><td><dl>Whether the value is an error.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l598">code »</a><span class="member"><a name="webdriver.promise.isPromise">webdriver.promise.isPromise</a> <span class="args">( value )</span> ⇒ <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code></span></div><p>Determines whether a <code >value</code> should be treated as a promise.
Any object whose "then" property is a function will be considered a promise.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>value: <code class="type">*</code><dd>The value to test.</dl><tr><th>Returns<tr><td><dl>Whether the value is a promise.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l800">code »</a><code class="type"><TYPE, SELF></code> <span class="member"><a name="webdriver.promise.map">webdriver.promise.map</a> <span class="args">( arr, fn, opt_self )</span></span></div><p>Calls a function for each element in an array and inserts the result into a
new array, which is used as the fulfillment value of the promise returned
by this function.
<p>If the return value of the mapping function is a promise, this function
will wait for it to be fulfilled before inserting it into the new array.
<p>If the mapping function throws or returns a rejected promise, the
promise returned by this function will be rejected with the same reason.
Only the first failure will be reported; all subsequent errors will be
silently ignored.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>arr: <code class="type">!(<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a>.<TYPE>|<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a>)</code><dd>The
array to iterator over, or a promise that will resolve to said array.<dt>fn: <code class="type">function(this: SELF, TYPE, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, !<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a>.<TYPE>): ?</code><dd>The
function to call for each element in the array. This function should
expect three arguments (the element, the index, and the array itself.<dt>opt_self: <code class="type">SELF=</code><dd>The object to be used as the value of 'this' within
<code >fn</code>.</dl></table></div></details></div></div><div class="wrap-details private"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2096">code »</a><span class="member"><a name="webdriver.promise.popFlow_">webdriver.promise.popFlow_</a> <span class="args">( )</span></span></div></summary></details></div></div><div class="wrap-details private"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2090">code »</a><span class="member"><a name="webdriver.promise.pushFlow_">webdriver.promise.pushFlow_</a> <span class="args">( flow )</span></span></div></summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>flow: <code class="type">!<a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code><dd>The new flow.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l655">code »</a><span class="member"><a name="webdriver.promise.rejected">webdriver.promise.rejected</a> <span class="args">( opt_reason )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Creates a promise that has been rejected with the given reason.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>opt_reason: <code class="type">*=</code><dd>The rejection reason; may be any value, but is
usually an Error or a string.</dl><tr><th>Returns<tr><td><dl>The rejected promise.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2068">code »</a><span class="member"><a name="webdriver.promise.setDefaultFlow">webdriver.promise.setDefaultFlow</a> <span class="args">( flow )</span></span></div><p>Changes the default flow to use when no others are active.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>flow: <code class="type">!<a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code><dd>The new default flow.</dl><tr><th>Throws<tr><td><dl><dt><code class="type"><a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Error">Error</a></code><dd>If the default flow is not currently active.</dl></table></div></details></div></div><div class="wrap-details public"><div><details class="function"><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l698">code »</a><span class="member"><a name="webdriver.promise.when">webdriver.promise.when</a> <span class="args">( value, opt_callback, opt_errback )</span> ⇒ <code class="type">!<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code></span></div><p>Registers an observer on a promised <code >value</code>, returning a new promise
that will be resolved when the value is. If <code >value</code> is not a promise,
then the return promise will be immediately resolved.</summary><div class="info"><table><tbody><tr><th>Parameters<tr><td><dl><dt>value: <code class="type">*</code><dd>The value to observe.<dt>opt_callback: <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function</a>=</code><dd>The function to call when the value is
resolved successfully.<dt>opt_errback: <code class="type"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function</a>=</code><dd>The function to call when the value is
rejected.</dl><tr><th>Returns<tr><td><dl>A new promise.</dl></table></div></details></div></div></section><section id="static-properties"><h2>Global Properties</h2><div class="wrap-details private"><div><details><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2060">code »</a><span class="member"><a name="webdriver.promise.activeFlows_">webdriver.promise.activeFlows_</a> : <code class="type">!<a href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a></code></span></div><p>A stack of active control flows, with the top of the stack used to schedule
commands. When there are multiple flows on the stack, the flow at index N
represents a callback triggered within a task owned by the flow at index
N-1.</summary></details></div></div><div class="wrap-details private"><div><details><summary><div><a class="source" href="source/lib/webdriver/promise.js.src.html#l2050">code »</a><span class="member"><a name="webdriver.promise.defaultFlow_">webdriver.promise.defaultFlow_</a> : <code class="type">!<a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code></span></div><p>The default flow to use if no others are active.</summary></details></div></div></section></main><nav id="topnav"><div><div id="menubutton"><label for="sidenav-toggle">Menu</label></div><form id="searchbox"><div><input type="search" placeholder="Search" tabindex="1"></div></form></div></nav><nav id="sidenav"><input type="checkbox" id="sidenav-types-ctrl" /><input type="checkbox" id="sidenav-files-ctrl" /><input type="checkbox" id="sidenav-modules-ctrl" /><a id="sidenav-overview"><div><h4>Overview</h4></div></a><div id="sidenav-types"><label for="sidenav-types-ctrl"><h4>Types</h4></label><i>No data</i></div><div id="sidenav-modules"><label for="sidenav-modules-ctrl"><h4>Modules</h4></label><i>No data</i></div><div id="sidenav-files"><label for="sidenav-files-ctrl"><h4>Files</h4></label><i>No data</i></div><a href="license.html"><div><h4>License</h4></div></a></nav><div id="push-footer"></div></div><footer><a href="https://github.com/jleyba/js-dossier">Generated by dossier</a></footer><script src="types.js"></script><script src="dossier.js"></script>