Document how we can control Promises

[fatso83]

There have been a couple of longstanding issues and pull requests regarding Promises on the lolex issue tracker.

I am assuming we will probably implement sinonjs/fake-timers#114 in time, for a totally synchronous way to control Promises, but for it to work fully in true ES2017+ environments using asynchronous/await it requires explicit support from the underlying engine.

Before it's implemented we should document for people how they can control Promises today in "normal" cases. We can't cover all cases (as mentioned above), but we could perhaps make a tutorial to show a possible path. I don't care about pretty in this regard, but results, so if it involves overriding Promise.prototype, installing Bluebird or other non-core Sinon libs that's ok. It's just about covering how to achieve a common desire, like the proxyquire article shows.

I am not totally sure how or what, but something ...

[benjamingr]

If you can guide me through this (set up goals and a format) I can work on this.

[fatso83]

I was thinking something along the lines of @mroderick's link seams article. So in the typical "tell ’em what you are going to tell ’em;tell ’em; and then tell ’em what you told ’em.” style I'd propose

• a quick intro to what the article is trying to cover
• case 1: problem, solution
• case 2: problem, solution
• summary

I am not totally sure about the cases, though... Might find something in our issue tracker? I am guessing people have trouble with stubbing time when relying on some method that relies on Promises. Some cases might when Promise's have been implemented internally in a library using setTimeout, setImmediate and similar, which are timers overridden by lolex.

With regards to goals:
A reader should be able to stub out time while still controlling some method that resolves to a promise?

[benjamingr]

Ok, do we want to show the examples with a particular library in mind (other than sinon or lolex)?

For example - in the context of testing async functions in mocha tests?

[fatso83]

Mocha is more or less the default, so use that. People use other stuff, but they have always seen that, and if not, it's easy enough to understand.

And I don't mind if we pull in stuff like Bluebird or stub global.Promise (although try to keep the dependency count as low as we can) if it gets the job done for the test. Right now, there is nothing, and a working example is better than perfect example. Let's just get something to point people to when they ask questions. Whatever we do, we should strive to make the examples as simple and pedagogical as possible without introducing too many concepts in each case, as that easily confuses more than helps.

[benjamingr]

I'd rather focus on writing an async test (for promises) and using fake timers - there are some interesting patterns based on promises waiting for a tick.

I'd rather avoid documenting the builtins we're discussing internally for a longer term solution (like exposing a %RunMicrotasks or flushing things.

Is there another guide I can look at (code link) so I can start working on it?

[fatso83]

We don't currently have any other guide guide or tutorial 😢

A tut covering async cases is a fine start in any case.

[benjamingr]

Ok, I've set myself a goal to do this in the coming month - cheers.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.