Fulfill or betray promises

[jandockx]

I recently switched to must from chai, because I started to used Standardjs.
I do find the reasons why you created must meaningful ("Beware of libraries that assert
on property access", "RFC 2119", …), and find myself happier with must than chai.

In both cases, I am frustrated with testing Promises.

The current must.resolve and must.reject primitives lead me to complex coding
structures, embedded in Promise.all([]) constructs far to often (the same applies to chai
and its extensions).

This is an example of a Mocha test:

const Gatherer = …
const domain = …
const getDataFailure = function(…) { … }

it('fails as described with a getData that fails', function () {
  const subject = new Gatherer({domain: domain, getData: getDataFailure})
  subject.domain.must.equal(domain)
  subject.getData.must.equal(getDataFailure)
  const initialised = subject.initialise(at)
  return Promise.all([
    initialised.must.reject,
    initialised.catch(err => {
      err.must.be.an.error(Error, /getting data/)
      subject.domain.must.equal(domain) // did not change
      subject.getData.must.equal(getDataFailure) // did not change
    })
  ])
})

Note that the initialised.must.reject phrase doesn't work. There is no simple way to
express that an AssertionError should be thrown when the promise resolves, without
doing something with this (initialised.must.reject.to…). To work, we would need
something of the form initialised.must.reject(), i.e., a method call.

If I want to say more about the returned value or error, and about the state of other
things after the promise settles, I seem to be forced to use complex Promise.all([])
constructs, and variables to store intermediate results.

In this PR, I offer an alternative that seems to work in my tests. We express that
a Promise must 'fulfill' or 'betrays' its intentions. The check fails if the Promise
does not settle in the way it must. If it does, the conditions that we express in
the 'fullfil' or 'betray' argument are tested.

The whole can be returned in a test, which is the most pleasing way most test frameworks
support asynchronous tests.

With these new methods, the above test now becomes:

it('fails as described with a getData that fails', function () {
  const subject = new Gatherer({domain: domain, getData: getDataFailure})
  subject.domain.must.equal(domain)
  subject.getData.must.equal(getDataFailure)
  return subject.initialise(at).must.betray(err => {
    err.must.be.an.error(Error, /getting data/)
    subject.domain.must.equal(domain) // did not change
    subject.getData.must.equal(getDataFailure) // did not change
  })
})

There is much less accidental complexity in this form.

More examples are in the JS Doc.

I you find to time, it would be nice if you could review this solution, and give me
any feedback that you deem relevant.