Namespace: webdriver.promise
View Source

class ControlFlow

final
webdriver.EventEmitter
  └ webdriver.promise.ControlFlow

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.

Each task scheduled within this flow may return a webdriver.promise.Promise to indicate it is an asynchronous operation. The ControlFlow will wait for such promises to be resolved before marking the task as completed.

Tasks and each callback registered on a webdriver.promise.Promise 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.

Each time a ControlFlow empties its task queue, it will fire an IDLE event. Conversely, whenever the flow terminates due to an unhandled error, it will remove all remaining tasks in its queue and fire an UNCAUGHT_EXCEPTION event. If there are no listeners registered with the flow, the error will be rethrown to the global error handler.

Instance Methods

annotateError(e)code »

deprecated

Appends a summary of this instance's recent task history to the given error's stack trace. This function will also ensure the error's stack trace is in canonical form.

Deprecated: Now a no-op; will be removed in 2.46.0.

Parameters
eError

The error to annotate.

Returns
Error

The annotated error.

await(promise)code »

deprecated

Schedules a task that will wait for another promise to resolve. The resolved promise's value will be returned as the task result.

Deprecated: Use wait(promise) instead.

Parameters
promisewebdriver.promise.Promise

The promise to wait on.

Returns
webdriver.promise.Promise

A promise that will resolve when the task has completed.

clearHistory()code »

deprecated

Clears this instance's task history.

Deprecated: Now a no-op; will be removed in 2.46.0.

<T> execute(fn, opt_description)code »

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 webdriver.promise.consume.

Parameters
fnfunction(): (T|webdriver.promise.Promise<T>)

The function to call to start the task. If the function returns a webdriver.promise.Promise, this instance will wait for it to be resolved before starting the next task.

opt_descriptionstring=

A description of the task.

Returns
webdriver.promise.Promise<T>

A promise that will be resolved with the result of the action.

getHistory()code »

deprecated

Returns a summary of the recent task activity for this instance. This includes the most recently completed task, as well as any parent tasks. In the returned summary, the task at index N is considered a sub-task of the task at index N+1.

Deprecated: Now a no-op; will be removed in 2.46.0.

Returns
Array<string>

A summary of this instance's recent task activity.

getSchedule(opt_includeStackTraces)code »

Generates an annotated string describing the internal state of this control flow, including the currently executing as well as pending tasks. If opt_includeStackTraces === true, the string will include the stack trace from when each task was scheduled.

Parameters
opt_includeStackTracesstring=

Whether to include the stack traces from when each task was scheduled. Defaults to false.

Returns
string

String representation of this flow's internal state.

reset()code »

Resets this instance, clearing its queue and removing all event listeners.

timeout(ms, opt_description)code »

Inserts a setTimeout into the command queue. This is equivalent to a thread sleep in a synchronous programming language.

Parameters
msnumber

The timeout delay, in milliseconds.

opt_descriptionstring=

A description to accompany the timeout.

Returns
webdriver.promise.Promise

A promise that will be resolved with the result of the action.

toString()code »

Returns a string representation of this control flow, which is its current schedule, sans task stack traces.

Returns
string

The string representation of this contorl flow.

<T> wait(condition, opt_timeout, opt_message)code »

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.

Condition functions may schedule sub-tasks with this instance, however, their execution time will be factored into whether a wait has timed out.

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.

If the condition function throws, or returns a rejected promise, the wait task will fail.

If the condition is defined as a promise, the flow will block on that promise's resolution, up to timeout milliseconds. If timeout === 0, the flow will block indefinitely on the promise's resolution.

Parameters
condition(webdriver.promise.Promise<T>|function(): ?)

The condition to poll, or a promise to wait on.

opt_timeoutnumber=

How long to wait, in milliseconds, for the condition to hold before timing out; defaults to 0.

opt_messagestring=

An optional error message to include if the wait times out; defaults to the empty string.

Returns
webdriver.promise.Promise<T>

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.

Throws
TypeError

If condition is not a function or promise or if timeout is not a number >= 0.

Types

ControlFlow.EventType

Events that may be emitted by an webdriver.promise.ControlFlow.