Tutorial for wait/async only has an incorrect example

[boxed]

The tutorial for using wait() ONLY has an incorrect example, it doesn't actually show you who to use it correctly! Took me quite a bit of time digging in the code an rereading the docs several times to understand that the trivial example is:

var done = false;
window.setTimeout(function() {
done = true;
}, 10);
wait(function(){return done;});
print(done);
// => false

print(done);
// => true

I suggest adding this trivial example in the tutorial and deleting the existing example. It's shorter AND shows what will actually work.

This all assuming my example above actually IS the correct way of doing it, it might be totally wrong :P

[boxed]

The reference documentation has this text: "Basically the test is split up by using the // => comments. Each chunk is executed independently, and the test may be paused at the point where the expected output is found." But then "Anytime you call wait() inside a section of code it tells the test runner to wait at the end of the test," These texts are in conflict.

If I put two sections like my example above after each other, then it does what I would expect: it runs the first block, waits for it to complete to validate the output, then continues with the next block.

This means the first text is incorrect. The two chunks are not executed independently.

[ianb]

Which example are you looking at that isn't right? I see this one in the tutorial:

var endpoint = location.href;
print(endpoint);
// => ...

var req = new XMLHttpRequest();
req.open("GET", endpoint);
req.onreadystatechange = function () {
  if (req.readyState != 4) {
    // hasn't actually finished
    return;
  }
  print("Result:", req.status, req.getResponseHeader('content-type'));
};
req.send();

wait(function () {return req.readyState == 4;});

print("Current state:", req.readyState);

/* =>
Current state: 1
Result: 200 text/html
*/

Of course there's a lot of different ways of using wait() – I personally end up using Spy("spy", {wait: true}) most of the time. What specific testing task tripped you up? Maybe a second example could clarify a different use case.

[boxed]

Yea, that's the one I mean. It's not that it's incorrect per se, the example is "correct", it's just super unhelpful! The wait() call can be removed and it's still exactly the same. Another section after where readyState is asserted against 4 would make the timing clear.

[ianb]

Well huh, I just now realize it says Current state: 1 – that's not right. Well, no, it's right... it's an example of the somewhat weird nature of watch(), but I suppose that isn't fully explained, so it's not very helpful.

[boxed]

The discussion on issue #17 got a little bit off track and now has a lot to do with this ticket :P

[boxed]

@ianb yea, that's exactly what I meant. Sorry I didn't manage to get that point across before :)

[boxed]

hmm... and I guess you mean "the weird nature of wait()"?