What does this sentence in the readme actually mean ("...use your imagination ...")

I consider this a documentation bug:

If you want to simulate asynchronous behavior, you have to use your imagination when calling the various functions.

This is ambiguous (and seems wrong to me) in a lot of ways. Please explain what exactly this is supposed to mean.

[benjamingr]

As JS is a language that in its concept runs atop an event-loop to allow manage async proceses in the background and scheduling/dispatching events in this way.

It is just that, I like it when talking about technical things to be precise and correct. I don’t think anyone is helped with things that don’t really make sense.

I hate to be that pedantic person but until ES2015 it was impossible to write async software in JavaScript.

The async bit came from the host environment. Even in ES2015 the async part is only “run to completion” microtask semantics and “real” asynchronicity comes from the platform.

You can plainly see this by looking at the fake-timers source code and seeing that there are a bunch of if/else depending on what platform we run on (since Node implements its own timers and the web implements the web timers spec). You can also trust me as both a maintainer here and a Node.js member (and also a WHATWG one, but I haven’t actually contributed to the timers spec) - but I am happy to provide references to any/all this.

---

Regardless of the technical/pedantic bit - please assume good faith (and competence) from maintainers of free libraries you use 😃

You are of course welcome to contribute docs back (please do) or (try and) pay Christian (or other people) to improve them.

(As a side note, we have a lot of “leaves a lot to be desired” docs in all other projects I’m a part of)

[mantoni]

Maybe I can help resolving the misunderstanding here.

It’s obviously possible to run async code in JS, and That was always the case. We can all agree on that. It’s also clear that test can be written that test this async behavior.

However, with the Sinon fake timers, it’s also possible to program the clock and cause timer invocations to be triggered by the test synchronously. When developers opt into doing this, they make assumptions about timings and how the Event queue works. While this is trivial in most cases, it’s easily possible to make wrong assumptions and cause code execution orders in tests that aren’t possible in “real life”.

Christians comment was referring to this fact, maybe in a not very clear way, back in the day, when Sinon was a young project, used by just a few. We’re aiming to have better documentation, now that Sinon matured and is used by a broad user base.

We’re just a handful of developers who do this in their spare time. I’d like to invite you to contribute to the documentation wherever you feel like things could be expressed more clearly.

❤️