scheduler.md

Schedulers

Many of the core features of jasminewd are centered around automatically synchronizing your tests with the WebDriver control flow. However, jasminewd can synchronize with any scheduler as long as it implements the following interface:

interface Scheduler {
  execute<T>(fn: () => Promise<T>|T): Promise<T>;
}

Where execute is the function used to put something on the scheduler. As long as your scheduler implements this interface, you can pass it into require('jasminewd2').init.

Custom Promise Implementation

Some schedulers need scheduled functions to use a specific implementation of the promise API. For instance, WebDriver has its ManagedPromise implementation, which it needs in order to track tasks across then() blocks. If your scheduler has its own promise implementation, you can implement the following interface:

interface SchedulerWithCustomPromises {
  execute<T>(fn: () => CustomPromise<T>|T): CustomPromise<T>;
  promise<T>(resolver: (resolve: (T) => void, reject: (any) => void) => void): CustomPromise<T>;
}

If the promise function is specified, jasminewd will use that function to generate all of its internal promises. If scheduler.promise is not specified, jasminewd will try to use WebDriver's ManagedPromise. If ManagedPromise is not available (e.g. the control flow is disabled), jasminewd will default to using native promises.

Idle API

If your scheduler requires a custom promise implementation, it is highly recommended that you implement the Idle API. This will help to mitigate issues with users who sometimes use other promise implementations (see #68 (comment)). To do this, implement the following interface:

var EventEmitter = require('events');

interface SchedulerWithIdleAPI extends EventEmitter {
  execute<T>(fn: () => CustomPromise<T>|T): CustomPromise<T>;
  promise<T>(resolver: (resolve: (T) => void, reject: (any) => void) => void): CustomPromise<T>;
  isIdle(): boolean;
}

Your scheduler must emit "idle" when it becomes idle.

Reset API

If you want your scheduler to be reset whenever a spec times out, implement the following interface:

interface SchedulerWithResetAPI {
  execute<T>(fn: () => CustomPromise<T>|T): CustomPromise<T>;
  reset(): void;
}

jasminewd will automatically look for a reset function and call it when specs time out. This is useful so that tasks from a timed out spec get cleared instead of continuing to tie up the scheduler and potentially getting executed during future specs.