selenium-webdriver
Version:
The official WebDriver JavaScript bindings from the Selenium project
109 lines • 17.5 kB
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>ControlFlow</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="parentlink"><b>Namespace:</b> <a href="namespace_webdriver_promise.html">webdriver.promise</a></div><div class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1231">View Source</a></div><h1>class ControlFlow</h1><div class="tags"><span>final</span></div><pre class="inheritance"><a href="class_webdriver_EventEmitter.html">webdriver.EventEmitter</a>
└ webdriver.promise.ControlFlow</pre><p>Handles the execution of scheduled tasks, each of which may be an
asynchronous operation. The control flow will ensure tasks are executed in
the ordered scheduled, starting each task only once those before it have
completed.</p>
<p>Each task scheduled within this flow may return a
<a href="class_webdriver_promise_Promise.html"><code>webdriver.promise.Promise</code></a> to indicate it is an asynchronous
operation. The ControlFlow will wait for such promises to be resolved before
marking the task as completed.</p>
<p>Tasks and each callback registered on a <a href="class_webdriver_promise_Promise.html"><code>webdriver.promise.Promise</code></a>
will be run in their own ControlFlow frame. Any tasks scheduled within a
frame will take priority over previously scheduled tasks. Furthermore, if any
of the tasks in the frame fail, the remainder of the tasks in that frame will
be discarded and the failure will be propagated to the user through the
callback/task's promised result.</p>
<p>Each time a ControlFlow empties its task queue, it will fire an
<a href="enum_webdriver_promise_ControlFlow_EventType.html#IDLE"><code>IDLE</code></a> event. Conversely,
whenever the flow terminates due to an unhandled error, it will remove all
remaining tasks in its queue and fire an
<a href="enum_webdriver_promise_ControlFlow_EventType.html#UNCAUGHT_EXCEPTION"><code>UNCAUGHT_EXCEPTION</code></a> event. If there are no listeners registered with the
flow, the error will be rethrown to the global error handler.</p>
<h3>new ControlFlow()</h3><div><div class="fn-details"><div><b>Parameters</b></div><dl><dd>None.</dl></div></div><h2>Instance Methods</h2><div id="addListener" class="function"><div><h3>addListener(<wbr>type, listenerFn, opt_scope)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l119">code »</a></span></h3><p>Registers a listener.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#addListener">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>The type of event to listen for.</p>
<dt>listenerFn<code>Function</code><dd><p>The function to invoke when the event is fired.</p>
<dt>opt_scope<code>?<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>=</code><dd><p>The object in whose scope to invoke the listener.</p>
</dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_EventEmitter.html">webdriver.EventEmitter</a></code><dd><p>A self reference.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="emit" class="function"><div><h3>emit(<wbr>type, var_args)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l47">code »</a></span></h3><p>Fires an event and calls all listeners.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#emit">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>The type of event to emit.</p>
<dt>var_args<code>...*</code><dd><p>Any arguments to pass to each listener.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="execute" class="function"><div><h3><code><T></code> execute(<wbr>fn, opt_description)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1488">code »</a></span></h3><p>Schedules a task for execution. If there is nothing currently in the
queue, the task will be executed in the next turn of the event loop. If
the task function is a generator, the task will be executed using
<a href="namespace_webdriver_promise.html#consume"><code>webdriver.promise.consume</code></a>.</p>
<div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>fn<code>function(): (T|<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><T>)</code><dd><p>The function to
call to start the task. If the function returns a
<a href="class_webdriver_promise_Promise.html"><code>webdriver.promise.Promise</code></a>, this instance will wait for it to be
resolved before starting the next task.</p>
<dt>opt_description<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>=</code><dd><p>A description of the task.</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>A promise that will be resolved
with the result of the action.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="getSchedule" class="function"><div><h3>getSchedule(<wbr>opt_includeStackTraces)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1380">code »</a></span></h3><p>Generates an annotated string describing the internal state of this control
flow, including the currently executing as well as pending tasks. If
<code>opt_includeStackTraces === true</code>, the string will include the
stack trace from when each task was scheduled.</p>
<div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>opt_includeStackTraces<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>=</code><dd><p>Whether to include the stack traces
from when each task was scheduled. Defaults to false.</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/String">string</a></code><dd><p>String representation of this flow's internal state.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="listeners" class="function"><div><h3>listeners(<wbr>type)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l74">code »</a></span></h3><p>Returns a mutable list of listeners for a specific type of event.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#listeners">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>The type of event to retrieve the listeners for.</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/Array">Array</a><{fn: Function, oneshot: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>, scope: ?(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)}></code><dd><p>The registered listeners for
the given event type.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="on" class="function"><div><h3>on(<wbr>type, listenerFn, opt_scope)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l145">code »</a></span></h3><p>An alias for <code>#addListener()</code>.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#on">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>The type of event to listen for.</p>
<dt>listenerFn<code>Function</code><dd><p>The function to invoke when the event is fired.</p>
<dt>opt_scope<code>?<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>=</code><dd><p>The object in whose scope to invoke the listener.</p>
</dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_EventEmitter.html">webdriver.EventEmitter</a></code><dd><p>A self reference.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="once" class="function"><div><h3>once(<wbr>type, listenerFn, opt_scope)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l133">code »</a></span></h3><p>Registers a one-time listener which will be called only the first time an
event is emitted, after which it will be removed.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#once">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>The type of event to listen for.</p>
<dt>listenerFn<code>Function</code><dd><p>The function to invoke when the event is fired.</p>
<dt>opt_scope<code>?<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>=</code><dd><p>The object in whose scope to invoke the listener.</p>
</dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_EventEmitter.html">webdriver.EventEmitter</a></code><dd><p>A self reference.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="removeAllListeners" class="function"><div><h3>removeAllListeners(<wbr>opt_type)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l176">code »</a></span></h3><p>Removes all listeners for a specific type of event. If no event is
specified, all listeners across all types will be removed.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#removeAllListeners">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>opt_type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>=</code><dd><p>The type of event to remove listeners from.</p>
</dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_EventEmitter.html">webdriver.EventEmitter</a></code><dd><p>A self reference.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="removeListener" class="function"><div><h3>removeListener(<wbr>type, listenerFn)<span class="codelink"><a href="source/lib/webdriver/events.js.src.html#l155">code »</a></span></h3><p>Removes a previously registered event listener.</p>
<p><b>Defined by: </b><a href="class_webdriver_EventEmitter.html#removeListener">webdriver.EventEmitter</a></p><div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>type<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code><dd><p>The type of event to unregister.</p>
<dt>listenerFn<code>Function</code><dd><p>The handler function to remove.</p>
</dl></div><div class="fn-details"><div><b>Returns</b></div><dl><dt><code><a href="class_webdriver_EventEmitter.html">webdriver.EventEmitter</a></code><dd><p>A self reference.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="reset" class="function"><div><h3>reset()<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1361">code »</a></span></h3><p>Resets this instance, clearing its queue and removing all event listeners.</p>
</div></div><hr class="fn-sep"><div id="timeout" class="function"><div><h3>timeout(<wbr>ms, opt_description)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1519">code »</a></span></h3><p>Inserts a <code>setTimeout</code> into the command queue. This is equivalent to
a thread sleep in a synchronous programming language.</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 timeout delay, in milliseconds.</p>
<dt>opt_description<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>=</code><dd><p>A description to accompany the timeout.</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 action.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="toString" class="function"><div><h3>toString()<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1353">code »</a></span></h3><p>Returns a string representation of this control flow, which is its current
<a href="class_webdriver_promise_ControlFlow.html#getSchedule"><code>schedule</code></a>, sans task stack traces.</p>
<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/String">string</a></code><dd><p>The string representation of this contorl flow.</p>
</dl></div></div></div></div><hr class="fn-sep"><div id="wait" class="function"><div><h3><code><T></code> wait(<wbr>condition, opt_timeout, opt_message)<span class="codelink"><a href="source/lib/webdriver/promise.js.src.html#l1562">code »</a></span></h3><p>Schedules a task that shall wait for a condition to hold. Each condition
function may return any value, but it will always be evaluated as a boolean.</p>
<p>Condition functions may schedule sub-tasks with this instance, however,
their execution time will be factored into whether a wait has timed out.</p>
<p>In the event a condition returns a Promise, the polling loop will wait for
it to be resolved before evaluating whether the condition has been satisfied.
The resolution time for a promise is factored into whether a wait has timed
out.</p>
<p>If the condition function throws, or returns a rejected promise, the
wait task will fail.</p>
<p>If the condition is defined as a promise, the flow will wait for it to
settle. If the timeout expires before the promise settles, the promise
returned by this function will be rejected.</p>
<p>If this function is invoked with <code>timeout === 0</code>, or the timeout is omitted,
the flow will wait indefinitely for the condition to be satisfied.</p>
<div><div class="fn-details"><div><b>Parameters</b></div><dl><dt>condition<code>(<a href="class_webdriver_promise_Promise.html">webdriver.promise.Promise</a><T>|function(): ?)</code><dd><p>The condition to poll,
or a promise to wait on.</p>
<dt>opt_timeout<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>=</code><dd><p>How long to wait, in milliseconds, for the
condition to hold before timing out. If omitted, the flow will wait
indefinitely.</p>
<dt>opt_message<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>=</code><dd><p>An optional error message to include if the
wait times out; defaults to the empty 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>A promise that will be fulfilled
when the condition has been satisified. The promise shall be rejected if
the wait times out waiting for the condition.</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 condition is not a function or promise or if timeout
is not a number >= 0.</p>
</dl></div></div></div></div><h2>Types</h2><dl><dt><a href="enum_webdriver_promise_ControlFlow_EventType.html">ControlFlow.EventType</a><dd><p>Events that may be emitted by an <a href="class_webdriver_promise_ControlFlow.html"><code>webdriver.promise.ControlFlow</code></a>.</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>