chore(async/await): document async/await better

Author: sjelin

README.md

@@ -15,6 +15,8 @@ Features
 
  - If a `done` function is passed to the test, waits for both the control flow and until done is called.
 
+ - If a test returns a promise, waits for both the the control flow and the promise to resolve.
+
  - Enhances `expect` so that it automatically unwraps promises before performing the assertion.
 
 Installation
@@ -58,3 +60,13 @@ describe('tests with webdriver', function() {
   });
 })
 ```
+
+`async` functions / `await`
+---------------------------
+
+`async` functions and the `await` keyword are likely coming in ES7, and
+available via several compilers.  At the moment, they often break the WebDriver
+control flow.
+([GitHub issue](https://github.com/SeleniumHQ/selenium/issues/3037)).  You can
+still use them, but if you do then you will have to use `await`/Promises for
+almost all your synchronization.  See `spec/asyncAwaitSpec.ts` for details.

spec/asyncAwaitSpec.ts

@@ -1,16 +1,34 @@
+/* Here we have an example of using async/await with jasminewd.  We are using
+ * typescript to gain access to async/await, but mostly this should look like
+ * normal javascript to you.
+ *
+ * The key thing to note here is that once you use async/await, the webdriver
+ * control flow is no longer reliable.  This means you have to use async/await
+ * or promises for all your asynchronous behavior.  In Protractor this would
+ * mean putting `await` before every line interacting with the browser.  In this
+ * example, we have to put `await` before `driver.sleep()`.
+ */
 "use strict";
 
+// Declare globals
 declare var describe;
 declare var it;
 declare var expect;
+declare var require;
 
-async function asyncHelper() {
-  return 7;
-}
+let driver = require('./common.js').getFakeDriver();
 
 describe('async function', function() {
+  let sharedVal: any;
   it('should wait on async functions', async function() {
-    let helperVal = await asyncHelper();
-    expect(helperVal).toBe(7);
+    sharedVal = await driver.getValueA(); // Async unwraps this to 'a'
+    expect(sharedVal).toBe('a');
+    await driver.sleep(1000); // Normally you wouldn't need to `await` this, but
+                              // the control flow is broken for async functions.
+    sharedVal = await driver.getValueB();
+  });
+
+  it('should have waited until the end of the last it() block', function() {
+    expect(sharedVal).toBe('b');
   });
 });