Class 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 {@link 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 {@link webdriver.promise.Deferred} will be run in their own ControlFlow frame. Any tasks scheduled within a frame will have priority over previously scheduled tasks. Furthermore, if any of the tasks in the frame fails, 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 {@link webdriver.promise.ControlFlow.EventType.IDLE} event. Conversely, whenever the flow terminates due to an unhandled error, it will remove all remaining tasks in its queue and fire an {@link webdriver.promise.ControlFlow.EventType.UNCAUGHT_EXCEPTION} event. If there are no listeners registered with the flow, the error will be rethrown to the global error handler.

extends

{webdriver.EventEmitter}

Hierarchy

Index

Constructor methods

Properties

Methods

Constructor methods

constructor(opt_timer?: IControlFlowTimer): ControlFlow

constructor

Parameters

  • opt_timer?: IControlFlowTimer optional

    The timer object to use. Should only be set for testing.

Returns

ControlFlow

Properties

public timer: IControlFlowTimer

The timer used by this instance.

type

{webdriver.promise.ControlFlow.Timer}

Methods

public addListener(type: string, listenerFn: any, opt_scope?: any): EventEmitter

Registers a listener.

Parameters

  • type: string

    The type of event to listen for.

  • listenerFn: any

    The function to invoke when the event is fired.

  • opt_scope?: any optional

    The object in whose scope to invoke the listener.

Returns

EventEmitter

A self reference.

public annotateError(e: any): any

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.

Parameters

  • e: any

    The error to annotate.

Returns

any

The annotated error.

public await(promise: Promise): Promise

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

Parameters

  • promise: Promise

    The promise to wait on.

Returns

Promise

A promise that will resolve when the task has completed.

public clearHistory()

Clears this instance's task history.

public emit(type: string, var_args?: Array<any>)

Fires an event and calls all listeners.

Parameters

  • type: string

    The type of event to emit.

  • var_args?: Array<any> optional

    Any arguments to pass to each listener.

public execute(fn: any, opt_description?: string): Promise

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.

Parameters

  • fn: any

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

  • opt_description?: string optional

    A description of the task.

Returns

Promise

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

public getHistory(): Array<string>

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.

Returns

Array<string>

A summary of this instance's recent task activity.

public getSchedule(): string

Returns

string

The scheduled tasks still pending with this instance.

public listeners(type: string): Array<{ fn: any; oneshot: boolean; scope: any; }>

Returns a mutable list of listeners for a specific type of event.

Parameters

  • type: string

    The type of event to retrieve the listeners for.

Returns

Array<{ fn: any; oneshot: boolean; scope: any; }>

{!Array.<{fn: !Function, oneshot: boolean, scope: (Object|undefined)}>} The registered listeners for the given event type.

public on(type: string, listenerFn: any, opt_scope?: any): EventEmitter

An alias for {@code #addListener()}.

Parameters

  • type: string

    The type of event to listen for.

  • listenerFn: any

    The function to invoke when the event is fired.

  • opt_scope?: any optional

    The object in whose scope to invoke the listener.

Returns

EventEmitter

A self reference.

public once(type: string, listenerFn: any, opt_scope?: any): EventEmitter

Registers a one-time listener which will be called only the first time an event is emitted, after which it will be removed.

Parameters

  • type: string

    The type of event to listen for.

  • listenerFn: any

    The function to invoke when the event is fired.

  • opt_scope?: any optional

    The object in whose scope to invoke the listener.

Returns

EventEmitter

A self reference.

public removeAllListeners(opt_type?: string): EventEmitter

Removes all listeners for a specific type of event. If no event is specified, all listeners across all types will be removed.

Parameters

  • opt_type?: string optional

    The type of event to remove listeners from.

Returns

EventEmitter

A self reference.

public removeListener(type: string, listenerFn: any): EventEmitter

Removes a previously registered event listener.

Parameters

  • type: string

    The type of event to unregister.

  • listenerFn: any

    The handler function to remove.

Returns

EventEmitter

A self reference.

public reset()

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

public timeout(ms: number, opt_description?: string): Promise

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

Parameters

  • ms: number

    The timeout delay, in milliseconds.

  • opt_description?: string optional

    A description to accompany the timeout.

Returns

Promise

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

public wait(condition: any, timeout: number, opt_message?: string): Promise

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.

Parameters

  • condition: any

    The condition function to poll.

  • timeout: number

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

  • opt_message?: string optional

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

Returns

Promise

A promise that will be resolved when the condition has been satisified. The promise shall be rejected if the wait times out waiting for the condition.