nmodule/js/rc/jasmine/promiseUtils

API Status: Private

Module with utility functions for running async Jasmine specs.

Description:

  • API Status: Private

    Module with utility functions for running async Jasmine specs.

Source:

Methods

(static) addCustomMatchers(specopt)

Description:

  • Adds custom matchers to the Jasmine instance
    (what is bound to this in a beforeEach function, for instance).

Source:
See:
Example
beforeEach(function () {
    promiseUtils.addCustomMatchers(this);
  });
  //or
  beforeEach(promiseUtils.addCustomMatchers);
Parameters:
Name Type Attributes Description
spec <optional>

The current Jasmine spec; if not given,
jasmine.getEnv().currentSpec will be used

(static) doPromise(promise, timeoutMessageopt, timeoutopt) → {Promise}

Description:

  • Runs a promise, using the Jasmine runs/waitsFor functions to ensure its
    completion. This function will verify that the promise is resolved -
    failing the promise will fail the test.

Source:
Example
promiseUtils.doPromise(editor.read()
    .then(function (result) {
      expect(result).toBe('my expected read value');
    }, function (err) {
      //not necessary to assert anything here - failing the promise will
      //automatically fail the test.
      //if you want to verify fail behavior, use toBeRejected() or
      //toBeRejectedWith() custom matchers.
    }));
Parameters:
Name Type Attributes Default Description
promise Promise
timeoutMessage String <optional>

optional message to present if timeout occurs
timeout Number <optional>
 5000

optional timeout in milliseconds
Returns:

promise that is verified to have been resolved
(if the input promise rejects, the test will fail).

Type
Promise

(static) enforcePromiseAPI()

Description:

  • Ensure that the following contract is followed when using doPromise and
    executePromise:

    • You may not call .then() on the result of doPromise().

    This ensures that doPromise() works correctly with the runs/waits async
    API presented by Jasmine 1.3.

Source:

(static) executePromise(promise, timeoutMessageopt, withinopt) → {Promise}

Description:

  • Runs a promise, using the Jasmine runs/waitsFor functions to ensure its
    completion. This method only cares that the promise is settled (resolved
    or rejected) - if you wish to assert that the promise resolves
    successfully, use doPromise instead.

Source:
Parameters:
Name Type Attributes Default Description
promise Promise
timeoutMessage String <optional>

optional message to present if timeout occurs
within Number <optional>
 5000

optional timeout in milliseconds
Returns:

promise that may be resolved or rejected

Type
Promise

(static) isTrackingReturnValues(spy) → {boolean}

Source:
Since:
  • Niagara 4.13
Parameters:
Name Type Description
spy function
Returns:

true if this is a spy function that is tracking return values

Type
boolean

(static) noConflict()

Description:

  • By default, promiseUtils augments Jasmine block execution to support
    returning promises from blocks and validating manual calls to
    doPromise, executePromise, and promise matchers.

    Call this to restore original Jasmine block execution. There will not
    typically be a reason to call this in practice, but it is provided just in
    case.

Source:

(static) prettyPrintBajaObjects()

Description:

  • when doing expect(method).toHaveBeenCalledWith(component), jasmine JSON
    stringifies the component to print the error. a component's JSON structure
    is so huge that this will actually lock up the browser and kill tests. i
    found myself having to do
    expect(method.mostRecentCall.args[0] === component).toBe(true).
    yuck. let's simplify the pretty printing a bit.

Source:

(static) trackSpyReturnValues()

Description:

  • Jasmine does not store return values by default. Patch it in so that each call object, in
    addition to object and args, stores a result property.

Source:
Since:
  • Niagara 4.13

(static) waitForCalled(func, timesopt, timeoutopt) → {Promise}

Description:

  • Return a promise that resolves after the given Jasmine spy has been called
    the specified number of times.

Source:
Parameters:
Name Type Attributes Default Description
func function

a Jasmine spy
times Number <optional>
 1

the number of times to expect the function to
have been called. Defaults to 1.
timeout Number <optional>
 5000

the time, in milliseconds, after which to give
up waiting and reject.
Returns:
Type
Promise

(static) waitForResolved(func, timesopt, timeoutopt) → {Promise.<(*|Array.<*>)>}

Description:

  • This will both wait for a spy function to be called, and for the promise it returns to be
    resolved.

    The spy must be tracking return values already - use .andTrackReturnValues(). This is so the
    matcher can monitor the resolution status of the returned promises.

Source:
Parameters:
Name Type Attributes Default Description
func
times Number <optional>
 1

the number of times to expect the function to
have been called. Defaults to 1.
timeout Number <optional>
 5000

the time, in milliseconds, after which to give
up waiting and reject.
Returns:

if times is omitted, this will resolve to the result
of the first call to the function. Otherwise, this will resolve to an array (of times length)
of that many calls to the function.

Type
Promise.<(*|Array.<*>)>

(static) waitForReturnedPromises()

Description:

  • Alters the default behavior of it(). If a Promise is returned from an
    it() call, Jasmine will wait for that promise to resolve (up to the
    default timeout) before completing the spec.

Source:
Example
promiseUtils.waitForReturnedPromises();

it('waits for a returned promise to resolve', function () {
  return promiseUtils.waitInterval(1000)
    .then(function () {
      expect('a').toBe('b'); //correctly fails, because Jasmine waited
    });
});

(static) waitForTrue(func, msgopt, timeoutopt) → {Promise}

Description:

  • Run a promise, using setTimeout to check for the truthiness of the
    condition function. This will not use waitsFor/runs and as such can be
    used in conjunction with doPromise/executePromise.

Source:
Parameters:
Name Type Attributes Description
func function

resolve the promise when this function returns a
truthy value, or a promise that resolves to a truthy value
msg String <optional>

the message to reject with upon timeout
timeout Number <optional>

the time, in milliseconds, after which to give
up waiting and reject
Returns:
Type
Promise

(static) waitInterval(intervalopt) → {Promise}

Description:

  • Return a promise that waits a certain number of milliseconds before
    resolving. This will not use waitsFor/runs and as such can be
    used in conjunction with doPromise/executePromise.

Source:
Parameters:
Name Type Attributes Default Description
interval Number <optional>
 0
Returns:
Type
Promise

Type Definitions

PromiseResolutionParams

Source:
Properties:
Name Type Attributes Description
within number <optional>

promise must settle within this many milliseconds
timeoutMessage string <optional>

fail the spec with this message if the promise does not
settle in time
Type:
  • object