Add sinon.promise() implementation

[mantoni]

Purpose (TL;DR)

This is an implementation of the feature request described in #2367 (sinon.promise()).

Background

The state of a promise can only be controlled by the promise itself. Also, promises do not expose their state, which makes it difficult to work with them in tests.

Solution

The sinon.promise([executor]) function returns a new promise with this additional API:

• status: The internal status of the promise, one of pending, resolved or rejected.
• resolvedValue: The promise resolved value.
• rejectedValue: The promise rejected value.
• resolve(value): Resolves the promise with the given value. Throws if the promise is not pending.
• reject(value): Rejects the promise with the given value. Throws if the promise is not pending.

A new promise can be created with a custom executor. This may be a fake or stub instance, or a custom function. If the custom executor resolves or rejects the promise, the above fields are populated accordingly.

Example:

var promise = sinon.promise(function (resolve) {
  resolve(42);
});

assert.equals(promise.status, "pending");
await promise;
assert.equals(promise.status, "resolved");
assert.equals(promise.resolvedValue, 42);

Furthermore the promise.resolve(value) and promise.reject(value) functions return promises, so that the caller can await until the sinon promise has settled. These promises always resolve successfully.

Example:

var promise = sinon.promise();
var error = new Error();

await promise.reject(error);

assert.equals(promise.status, "rejected");
assert.same(promise.rejectedValue, error);

How to verify

1. Check out this branch
2. npm install
3. npm test

Checklist for author

• npm run lint passes
• References to standard library functions are cached.

[mroderick]

This looks good 👍

Would you mind adding some documentation in the Jekyll site, so users can learn how to use it?

[mroderick]

Is there any reason not to use await wrapped in try/catch instead of then/catch on the promise?

Suggested change

	promise
	.then(function (val) {
	status = "fulfilled";
	value = val;
	})
	.catch(function (reason) {
	status = "rejected";
	value = reason;
	});
	try {
	status = "fulfilled";
	value = await promise;
	} catch (reason) {
	status = "rejected";
	value = reason;
	}

[mantoni]

Yes, there is a good reason: We don't want to await the promise, because we want to know if the promise is still pending. I committed your suggestion, but then there's a test failure and I reverted.

[mantoni]

Thanks for reviewing. Before spending time on writing documentation, I wanted to get some feedback.

We can keep iterating on this PR for a bit until everyone is happy with the API and implementation.

[mantoni]

I have made some minor changes and added a documentation page. I cannot see the new documentation page locally for reasons I don't understand.

[fatso83]

@mantoni This is a problem with the docs setup: it does not have a way of showing release-source (not copied to site), so you will not see your changes until they have been versioned ... This is less than great, but I have fixed it locally by manualyl including release-source in the build and not commiting the change.