Module: nmodule/js/rc/jasmine/promiseUtils

Methods

---

<static> addCustomMatchers( [spec])

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

Parameters:

Name	Type	Argument	Description
spec		<optional>	The current Jasmine spec; if not given, jasmine.getEnv().currentSpec will be used

See:

• CustomMatchers

Example

beforeEach(function () {
    promiseUtils.addCustomMatchers(this);
  });
  //or
  beforeEach(promiseUtils.addCustomMatchers);

---

<static> doPromise(promise [, timeoutMessage] [, timeout])

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.

Parameters:

Name	Type	Argument	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

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.
    }));

---

<static> enforcePromiseAPI()

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

• You may not call doPromise() or executePromise() more than once
  during a single call to it(), beforeEach(), or afterEach().
• You may not call .then() on the result of doPromise().
• You may not nest one call to doPromise() inside of another.

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

---

<static> executePromise(promise [, timeoutMessage] [, timeout])

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.

Parameters:

Name	Type	Argument	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 may be resolved or rejected

Type

Promise

---

<static> noConflict()

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.

---

<static> waitForCalled(func [, times] [, timeout])

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

Parameters:

Name	Type	Argument	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> waitForReturnedPromises()

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.

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 [, msg] [, timeout])

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.

Parameters:

Name	Type	Argument	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( [interval])

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.

Parameters:

Name	Type	Argument	Default	Description
interval	Number	<optional>	0

Returns:

Type

Promise