{"action":"created","issue":{"url":"https://api.github.com/repos/emberjs/guides/issues/1161","labels_url":"https://api.github.com/repos/emberjs/guides/issues/1161/labels{/name}","comments_url":"https://api.github.com/repos/emberjs/guides/issues/1161/comments","events_url":"https://api.github.com/repos/emberjs/guides/issues/1161/events","html_url":"https://github.com/emberjs/guides/issues/1161","id":125979474,"number":1161,"title":"Improve documentation on async test helpers' return values","user":{"login":"kdhquickitt","id":16650695,"avatar_url":"https://avatars.githubusercontent.com/u/16650695?v=3","gravatar_id":"","url":"https://api.github.com/users/kdhquickitt","html_url":"https://github.com/kdhquickitt","followers_url":"https://api.github.com/users/kdhquickitt/followers","following_url":"https://api.github.com/users/kdhquickitt/following{/other_user}","gists_url":"https://api.github.com/users/kdhquickitt/gists{/gist_id}","starred_url":"https://api.github.com/users/kdhquickitt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kdhquickitt/subscriptions","organizations_url":"https://api.github.com/users/kdhquickitt/orgs","repos_url":"https://api.github.com/users/kdhquickitt/repos","events_url":"https://api.github.com/users/kdhquickitt/events{/privacy}","received_events_url":"https://api.github.com/users/kdhquickitt/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/emberjs/guides/labels/help%20wanted","name":"help wanted","color":"159818"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2016-01-11T16:17:31Z","updated_at":"2016-01-26T05:55:40Z","closed_at":null,"body":"The \"looks like they are blocking calls\" aspect of async test is extremely cool, and clearly requires a great deal of internal magic.  Unfortunately, the complexity of that magic makes it difficult for mere mortals to understand.  In addition, one cannot be certain what portions of existing behavior are part of the API \"contract\" and what might be implementation details subject to change.\r\n\r\nThe root problem is that neither the documentation on the registerAsyncHelper function  (http://emberjs.com/api/classes/Ember.Test.html#method_registerAsyncHelper) nor the testing guides (https://guides.emberjs.com/v2.2.0/testing/acceptance/) provide any indication on the contract between Ember and the return value of the function that implements the async test helper.  \r\n\r\n\"Built-in\" async test helpers such as \"click\" all seem to end with \r\n\r\n    return app.testHelpers.wait();\r\n\r\nwhich returns a `Promise` that waits for a variety of activity within the system to die down.  From that, one might intuit that it is the return of that `Promise` that implements the \"wait for activity to complete\" behavior.  The examples within the guides, however (and the example given in the API) do _not_ return a value, and yet exhibit the same behavior.  (More magic.)\r\n\r\nThis leads to questions like:\r\n\r\n1. If an async test helper returns a `Promise`, is Ember guaranteed to wait for the `Promise` to be resolved before moving on?  (i.e. before that async helper \"appears\" to return so that the next line in the test case executes)\r\n2. If so, is an async helper allowed to return _any_ kind of `Promise`, or must the `Promise` be (or chain to) the one returned by `app.testHelpers.wait()`?\r\n3. How, if at all, does the behavior of an async helper differ if it returns a `Promise` as opposed to returning nothing?\r\n4. What is the relationship between a `Promise` returned by an async helper and the `Promise`s returned by any other async helpers that it calls?  (Example: the sample in the guide calls 'visit' and 'click', both of which return `app.testHelpers.wait()`.  What if that helper had also returned a `Promise`?  What, if any, linkages are established between those `Promise`s?\r\n5. Under what situations (if any) would returning the `Promise` generated by `app.testHelpers.wait()` be _required_?\r\n6. The API documentation includes the statement `All async helpers after it will wait for it complete before running.`.  What about \"regular\" (non-async) helpers?  Do they get delayed as well?  Or can one not follow a call to an async helper with a call to a \"sync\" helper?\r\n\r\nWith regard to `Promise`s other than that generated by `app.testHelpers.wait()`, there are a number of cases that I can think of where one might want to write an async helper that did not actually trigger any activity inside Ember itself.  For example, suppose that one was writing a \"full\" acceptance test that actually communicated with a back-end service (as opposed to having the communications mocked out.)  In this case, one might want to:\r\n\r\n1. Execute an Ajax transaction at the beginning of a test case in order to set up preconditions in the back end for that test case.\r\n2. Execute an Ajax transaction at the end of a test case in order to verify that post-conditions on the back end have been satisfied.\r\n\r\nIn these cases, one might want to return a \"vanilla\" `Promise` that would resolve when the ajax transaction completed, and not to have the async helper complete until that `Promise` resolved.  (Yes, I know that `app.testHelpers.wait()` seems to wait for transactions run through Ember.$.ajax to complete, but what if one didn't use Ember.$.ajax?  Can that be made to work?  Or is the participation of  `app.testHelpers.wait()` required?)\r\n\r\nThus, a better statement of how Ember uses the return value from the async test helper function, and possible an example or two that involve the creation of an async helper that isn't just a call to pre-defined async helpers, would be _really_ useful."},"comment":{"url":"https://api.github.com/repos/emberjs/guides/issues/comments/174848368","html_url":"https://github.com/emberjs/guides/issues/1161#issuecomment-174848368","issue_url":"https://api.github.com/repos/emberjs/guides/issues/1161","id":174848368,"user":{"login":"ppcano","id":825430,"avatar_url":"https://avatars.githubusercontent.com/u/825430?v=3","gravatar_id":"","url":"https://api.github.com/users/ppcano","html_url":"https://github.com/ppcano","followers_url":"https://api.github.com/users/ppcano/followers","following_url":"https://api.github.com/users/ppcano/following{/other_user}","gists_url":"https://api.github.com/users/ppcano/gists{/gist_id}","starred_url":"https://api.github.com/users/ppcano/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ppcano/subscriptions","organizations_url":"https://api.github.com/users/ppcano/orgs","repos_url":"https://api.github.com/users/ppcano/repos","events_url":"https://api.github.com/users/ppcano/events{/privacy}","received_events_url":"https://api.github.com/users/ppcano/received_events","type":"User","site_admin":false},"created_at":"2016-01-26T05:55:40Z","updated_at":"2016-01-26T05:55:40Z","body":"1) I also missed a better description on how the `async test helper` works when the `helper` returns  `app.testHelpers.wait()`.\r\n\r\nI am not sure if the [wait documentation](http://emberjs.com/api/classes/Ember.Test.html#method_wait) wants to provide this kind of low-level description, but IMHO, this could also be reviewed:\r\n\r\n- Add to the [registerAsyncHelper documentation](http://emberjs.com/api/classes/Ember.Test.html#method_registerAsyncHelper) that the helper can or should return a promise to provide when the async operation finishes.\r\n\r\n- Add to [wait documentation](http://emberjs.com/api/classes/Ember.Test.html#method_wait) that returns a promise which will be resolved when the following operations finish:\r\n  - routing loads\r\n  - ajax requests\r\n  - scheduled run loop\r\n  - waiters\r\n\r\n2) The [custom test helper guide](https://guides.emberjs.com/v2.3.0/testing/acceptance/#toc_custom-test-helpers) may introduce the `registerWaiter` API and provides an example which describes how the `registerWaiter` method can be used inside an `async test helper` .\r\n\r\nThis [waitUntil helper](http://discuss.emberjs.com/t/waituntil-async-helper-feedback/9444) could be useful   for documentation purpose.\r\n"}}