mocha: 🐛 Bug: Support `setImmediate` between hooks on Promises

And it makes it almost impossible to use mocha for testing constructs like Promises where whether something happens in same or next tick is part of what the tests are meant to check.

My gut instinct here is that if the behavior occurring within a tick is what’s being tested then it belongs inside the test. E.g. instead of this:

describe("my promise", function() {
  var myPromise
  before|beforeEach(function() {
    myPromise = MyPromise.resolve(42)
  })
  it("should wait a tick to resolve", function() {
    assert(myPromise.isPending())
  })
  it("should use the resolved value", function() {
    return myPromise.then(function(value) {
      assert(value === 42)
    })
  })
  it("should have whatever other special behavior", function() {
    return doWhateverWith(myPromise)
  })
})

…do this instead (although it looks a little awkward):

describe("my promise", function() {
  var myPromise
  before|beforeEach(function() {
    myPromise = MyPromise.resolve(42)
  })
  it("should wait a tick to resolve", function() {
    // test how quickly it resolves -- so not reusing the usual value for the suite in this test case
    assert(MyPromise.resolve().isPending())
  })
  it("should use the resolved value", function() {
    return myPromise.then(function(value) {
      assert(value === 42)
    })
  })
  it("should have whatever other special behavior", function() {
    return doWhateverWith(myPromise)
  })
})

A much stronger case, in my opinion, is https://github.com/domenic/chai-as-promised/issues/173#issuecomment-330409841 – which essentially means that there is no way to set up a rejected promise before the test (once Node starts treating unhandled rejections the same way it treats unhandled exceptions). Is there some workaround – some way to define what the promise will be/do but not eagerly run it? Maybe something like this?

describe("my promise", function() {
  var makeMyPromise
  before(function() { // equivalent to beforeEach due to thunk
    makeMyPromise = function() { return MyPromise.reject(new Error("example")) }
  })
  // or
  var makeMyPromise
  before(function() {
    // WARNING: in this version the *first* test must handle the rejection,
    // and all subsequent tests are allowed to ignore it even if they shouldn't!
    var cache
    makeMyPromise = function() {
      if (!cache) { cache = MyPromise.reject(new Error("example")) }
      return cache
    }
  })
  // or
  function makeMyPromise() { // equivalent to beforeEach due to thunk
    return MyPromise.reject(new Error("example"))
  }
  // end or branches
  it("should wait a tick to complete", function() {
    var promise = makeMyPromise()
    assert(promise.isPending())
    // the end value/result of this promise is not relevant in this test: hack to suppress rejection warning/error
    promise.catch(function() {})
    // note that in the caching version,
    // provided the below test for `catch`ing is moved up to be the first test,
    // this can be simplified to `assert(makeMyPromise().isPending())`;
    // but that version will prevent any warnings about any subsequent test that forgets to handle it!
  })
  it("should use the rejected error", function() {
    return makeMyPromise().catch(function(error) {
      assert(error.message === "example")
    })
  })
  it("should have whatever other special behavior", function() {
    return doWhateverWith(makeMyPromise())
  })
})

There’s a downside that one has to know about the problem and this solution. Might be other downsides I’m missing at this point. This also exposes an inherent conflict between “if I create a new promise for each test then every test must handle the rejection even if it’s irrelevant” and “if I reuse a promise then the first test handling its rejection would allow the rest to ignore it whether they should or not”*; but I am pretty sure that issue is going to be present regardless of how the promise is created or whether and where it’s stored.

*(EDITTED TO ADD: you could bypass the need for the first test to be the one that handles the rejection if you immediately .catch(function() {}) the promise to suppress the error – without saving the caught version so you can still examine the rejection in the original – in fact, the real danger I’m getting at is that even if you use the first-test-catches approach instead of that obvious hack it has the same effect on the rest of the tests as the hack would.)

Consistency around the hook behavior is needed, but more importantly users just need to know what to expect. It doesn’t work quite right atm, and there’s an open discussion (though dormant) about how various failure conditions in the hooks should impact the tests.

I’m 99% sure the intent of setImmediate(fn) was “execute this before setTimeout(fn) would.”

So yeah, bug. Thanks 👍