selenium-webdriver

<!DOCTYPE html><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no"><meta http-equiv="Content-Language" content="en"><meta http-equiv="X-UA-Compatible" content="IE=edge"><title>webdriver.promise</title><link href="dossier.css" rel="stylesheet" type="text/css"><header><div><form><div><input type="search" placeholder="Search" tabindex="1"></div></form></div></header><main><article><div class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l52">View Source</a></div><h1>namespace webdriver.promise</h1><p>A promise implementation based on the CommonJS promise/A and promise/B proposals. For more information, see http://wiki.commonjs.org/wiki/Promises.</p> <h2>Functions</h2><div id="all" class="function"><div><h3><code><T></code> all(<wbr>arr)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l939">code »</a></span></h3><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.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>arr<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><(T|<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><T>)></code><dd><p>An array of promises to wait on.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><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/Array">Array</a><T>></code><dd><p>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.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="asap" class="function"><div><h3>asap(<wbr>value, callback, opt_errback)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l909">code »</a></span></h3><p>Invokes the appropriate callback function as soon as a promised <code>value</code> is resolved. This function is similar to <a href="namespace_webdriver_promise.html#when"><code>webdriver.promise.when</code></a>, except it does not return a new promise.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>value<code>*</code><dd><p>The value to observe.</p> <dt>callback<code>Function</code><dd><p>The function to call when the value is resolved successfully.</p> <dt>opt_errback<code>?Function=</code><dd><p>The function to call when the value is rejected.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="captureStackTrace" class="function"><div><h3>captureStackTrace(<wbr>name, msg, topFn)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l84">code »</a></span></h3><p>Generates an error to capture the current stack trace.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>name<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>Error name for this stack trace.</p> <dt>msg<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>Message to record.</p> <dt>topFn<code>Function</code><dd><p>The function that should appear at the top of the stack; only applicable in V8.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a></code><dd><p>The generated error.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="checkedNodeCall" class="function"><div><h3>checkedNodeCall(<wbr>fn, var_args)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l862">code »</a></span></h3><p>Wraps a function that expects a node-style callback as its final argument. This callback expects two arguments: an error value (which will be null if the call succeeded), and the success value as the second argument. The callback will the resolve or reject the returned promise, based on its arguments.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>fn<code>Function</code><dd><p>The function to wrap.</p> <dt>var_args<code>...?</code><dd><p>The arguments to apply to the function, excluding the final callback.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code><dd><p>A promise that will be resolved with the result of the provided function's callback.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="consume" class="function"><div><h3>consume(<wbr>generatorFn, opt_self, var_args)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l2567">code »</a></span></h3><p>Consumes a <code>GeneratorFunction</code>. Each time the generator yields a promise, this function will wait for it to be fulfilled before feeding the fulfilled value back into <code>next</code>. Likewise, if a yielded promise is rejected, the rejection error will be passed to <code>throw</code>.</p> <p><strong>Example 1:</strong> the Fibonacci Sequence.</p> <pre><code>promise.consume(function* fibonacci() { var n1 = 1, n2 = 1; for (var i = 0; i < 4; ++i) { var tmp = yield n1 + n2; n1 = n2; n2 = tmp; } return n1 + n2; }).then(function(result) { console.log(result); // 13 }); </code></pre> <p><strong>Example 2:</strong> a generator that throws.</p> <pre><code>promise.consume(function* () { yield promise.delayed(250).then(function() { throw Error('boom'); }); }).thenCatch(function(e) { console.log(e.toString()); // Error: boom }); </code></pre> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>generatorFn<code>Function</code><dd><p>The generator function to execute.</p> <dt>opt_self<code>?<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>=</code><dd><p>The object to use as "this" when invoking the initial generator.</p> <dt>var_args<code>...*</code><dd><p>Any arguments to pass to the initial generator.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><?></code><dd><p>A promise that will resolve to the generator's final result.</p> </dl></div><div class="fn-details"><div><b>Throws</b></div><dl><dt><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError">TypeError</a></code><dd><p>If the given function is not a generator.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="controlFlow" class="function"><div><h3>controlFlow()<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l2496">code »</a></span></h3><div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code><dd><p>The currently active control flow.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="createFlow" class="function"><div><h3>createFlow(<wbr>callback)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l2511">code »</a></span></h3><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.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>callback<code>function(<a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a>): ?</code><dd><p>The entry point to the newly created flow.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code><dd><p>A promise that resolves to the callback result.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="defer" class="function"><div><h3><code><T></code> defer()<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l813">code »</a></span></h3><p>Creates a new deferred object.</p> <div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Deferred.html">webdriver.promise.Deferred</a><T></code><dd><p>The new deferred object.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="delayed" class="function"><div><h3>delayed(<wbr>ms)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l793">code »</a></span></h3><p>Creates a promise that will be resolved at a set time in the future.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>ms<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code><dd><p>The amount of time, in milliseconds, to wait before resolving the promise.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code><dd><p>The promise.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="filter" class="function"><div><h3><code><TYPE, SELF></code> filter(<wbr>arr, fn, opt_self)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1042">code »</a></span></h3><p>Calls a function for each element in an array, and if the function returns true adds the element to a new array.</p> <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> <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.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>arr<code>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><TYPE>|<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/Array">Array</a><TYPE>>)</code><dd><p>The array to iterator over, or a promise that will resolve to said array.</p> <dt>fn<code>function(this: SELF, TYPE, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/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><p>The function to call for each element in the array.</p> <dt>opt_self<code>?SELF=</code><dd><p>The object to be used as the value of 'this' within <code>fn</code>.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="fulfilled" class="function"><div><h3><code><T></code> fulfilled(<wbr>opt_value)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l824">code »</a></span></h3><p>Creates a promise that has been resolved with the given value.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>opt_value<code>?T=</code><dd><p>The resolved value.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><T></code><dd><p>The resolved promise.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="fullyResolved" class="function"><div><h3>fullyResolved(<wbr>value)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1096">code »</a></span></h3><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.</p> <p>Warning: This function makes no checks against objects that contain cyclical references:</p> <pre><code>var value = {}; value['self'] = value; promise.fullyResolved(value); // Stack overflow. </code></pre> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>value<code>*</code><dd><p>The value to fully resolve.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code><dd><p>A promise for a fully resolved version of the input value.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="isGenerator" class="function"><div><h3>isGenerator(<wbr>fn)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l2524">code »</a></span></h3><p>Tests is a function is a generator.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>fn<code>Function</code><dd><p>The function to test.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code><dd><p>Whether the function is a generator.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="isPromise" class="function"><div><h3>isPromise(<wbr>value)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l777">code »</a></span></h3><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.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>value<code>*</code><dd><p>The value to test.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code><dd><p>Whether the value is a promise.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="map" class="function"><div><h3><code><TYPE, SELF></code> map(<wbr>arr, fn, opt_self)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l987">code »</a></span></h3><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> <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> <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.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>arr<code>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><TYPE>|<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/Array">Array</a><TYPE>>)</code><dd><p>The array to iterator over, or a promise that will resolve to said array.</p> <dt>fn<code>function(this: SELF, TYPE, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><TYPE>): ?</code><dd><p>The function to call for each element in the array. This function should expect three arguments (the element, the index, and the array itself.</p> <dt>opt_self<code>?SELF=</code><dd><p>The object to be used as the value of 'this' within <code>fn</code>.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="rejected" class="function"><div><h3><code><T></code> rejected(<wbr>opt_reason)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l841">code »</a></span></h3><p>Creates a promise that has been rejected with the given reason.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>opt_reason<code>*=</code><dd><p>The rejection reason; may be any value, but is usually an Error or a string.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><T></code><dd><p>The rejected promise.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="setDefaultFlow" class="function"><div><h3>setDefaultFlow(<wbr>flow)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l2485">code »</a></span></h3><p>Changes the default flow to use when no others are active.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>flow<code><a href="class_webdriver_promise_ControlFlow.html">webdriver.promise.ControlFlow</a></code><dd><p>The new default flow.</p> </dl></div><div class="fn-details"><div><b>Throws</b></div><dl><dt><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a></code><dd><p>If the default flow is not currently active.</p> </dl></div></div></div></div><hr class="fn-sep"><div id="when" class="function"><div><h3>when(<wbr>value, opt_callback, opt_errback)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l888">code »</a></span></h3><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.</p> <div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>value<code>*</code><dd><p>The value to observe.</p> <dt>opt_callback<code>?Function=</code><dd><p>The function to call when the value is resolved successfully.</p> <dt>opt_errback<code>?Function=</code><dd><p>The function to call when the value is rejected.</p> </dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a></code><dd><p>A new promise.</p> </dl></div></div></div></div><h2>Compiler Constants</h2><div id="LONG_STACK_TRACES" class="property"><dl><dt><a href="source/lib/webdriver/promise.js.src.html#l70">LONG_STACK_TRACES</a><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code><dd><p>Whether to append traces of <code>then</code> to rejection errors.</p> </dl></div><h2>Types</h2><dl><dt><a href="class_webdriver_promise_CancellationError.html">CancellationError</a><dd><p>Error used when the computation of a promise is cancelled.</p> <dt><a href="class_webdriver_promise_ControlFlow.html">ControlFlow</a><dd><p>Handles the execution of scheduled tasks, each of which may be an asynchronous operation.</p> <dt><a href="class_webdriver_promise_Deferred.html">Deferred</a><dd><p>Represents a value that will be resolved at some point in the future.</p> <dt><a href="class_webdriver_promise_Promise.html">Promise</a><dd><p>Represents the eventual value of a completed operation.</p> <dt><a href="interface_webdriver_promise_Thenable.html">Thenable</a><dd><p>Thenable is a promise-like object with a <code>then</code> method which may be used to schedule callbacks on a promised value.</p> </dl></article><nav><h3><a href="index.html" tabindex="2">Overview</a></h3><div><input type="checkbox" id="nav-modules" checked/><label for="nav-modules"><h3><span class="selectable" tabindex="2">Modules</span></h3></label><div id="nav-modules-view"></div></div><div><input type="checkbox" id="nav-types" checked/><label for="nav-types"><h3><span class="selectable" tabindex="2">Types</span></h3></label><div id="nav-types-view"></div></div><h3><a href="Changes.html" tabindex="2">Changes</a></h3></nav></main><footer><div><a href="https://github.com/jleyba/js-dossier">Generated by dossier</a></div></footer><script src="types.js"></script><script src="dossier.js"></script>