refactor(testing): reenable injectAsync checking for return value

Before #5375, injectAsync would check the return value and fail
if it was not a promise, to help users remember that they need to
return a promise from an async test. #5375 removed that with the
introduction of the testing zone.

This un-deprecates `injectAsync` until we can resolve
https://github.com/angular/angular/issues/5515.

To be clear, this means that `inject` and `injectAsync` are now
identical except that `injectAsync` will fail if the test
does not return a promise, and `inject` will fail if the test
returns any value.

Closes #5721

modules/angular2/src/testing/test_injector.ts

@@ -142,9 +142,7 @@ export function createTestInjectorWithRuntimeCompiler(
 }
 
 /**
- * Allows injecting dependencies in `beforeEach()` and `it()`. When using with the
- * `angular2/testing` library, the test function will be run within a zone and will
- * automatically complete when all asynchronous tests have finished.
+ * Allows injecting dependencies in `beforeEach()` and `it()`.
  *
  * Example:
  *
@@ -155,9 +153,8 @@ export function createTestInjectorWithRuntimeCompiler(
  * }));
  *
  * it('...', inject([AClass], (object) => {
- *   object.doSomething().then(() => {
- *     expect(...);
- *   });
+ *   object.doSomething();
+ *   expect(...);
  * })
  * ```
  *
@@ -174,7 +171,22 @@ export function inject(tokens: any[], fn: Function): FunctionWithParamTokens {
 }
 
 /**
- * @deprecated Use inject instead, which now supports both synchronous and asynchronous tests.
+ * Allows injecting dependencies in `beforeEach()` and `it()`. The test must return
+ * a promise which will resolve when all asynchronous activity is complete.
+ *
+ * Example:
+ *
+ * ```
+ * it('...', injectAsync([AClass], (object) => {
+ *   return object.doSomething().then(() => {
+ *     expect(...);
+ *   });
+ * })
+ * ```
+ *
+ * @param {Array} tokens
+ * @param {Function} fn
+ * @return {FunctionWithParamTokens}
  */
 export function injectAsync(tokens: any[], fn: Function): FunctionWithParamTokens {
   return new FunctionWithParamTokens(tokens, fn, true);

modules/angular2/src/testing/testing.ts

@@ -192,9 +192,26 @@ function _it(jsmFn: Function, name: string, testFn: FunctionWithParamTokens | An
         injector = createTestInjectorWithRuntimeCompiler(testProviders);
       }
 
-      var returnedTestValue = runInTestZone(() => testFn.execute(injector), done, done.fail);
-      if (_isPromiseLike(returnedTestValue)) {
-        (<Promise<any>>returnedTestValue).then(null, (err) => { done.fail(err); });
+      var finishCallback = () => {
+        // Wait one more event loop to make sure we catch unreturned promises and
+        // promise rejections.
+        setTimeout(done, 0);
+      };
+      var returnedTestValue =
+          runInTestZone(() => testFn.execute(injector), finishCallback, done.fail);
+
+      if (testFn.isAsync) {
+        if (_isPromiseLike(returnedTestValue)) {
+          (<Promise<any>>returnedTestValue).then(null, (err) => { done.fail(err); });
+        } else {
+          done.fail('Error: injectAsync was expected to return a promise, but the ' +
+                    ' returned value was: ' + returnedTestValue);
+        }
+      } else {
+        if (!(returnedTestValue === undefined)) {
+          done.fail('Error: inject returned a value. Did you mean to use injectAsync? Returned ' +
+                    'value was: ' + returnedTestValue);
+        }
       }
     }, timeOut);
   } else {
@@ -220,13 +237,30 @@ export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
   if (fn instanceof FunctionWithParamTokens) {
     // The test case uses inject(). ie `beforeEach(inject([ClassA], (a) => { ...
     // }));`
-
     jsmBeforeEach((done) => {
+      var finishCallback = () => {
+        // Wait one more event loop to make sure we catch unreturned promises and
+        // promise rejections.
+        setTimeout(done, 0);
+      };
       if (!injector) {
         injector = createTestInjectorWithRuntimeCompiler(testProviders);
       }
 
-      runInTestZone(() => fn.execute(injector), done, done.fail);
+      var returnedTestValue = runInTestZone(() => fn.execute(injector), finishCallback, done.fail);
+      if (fn.isAsync) {
+        if (_isPromiseLike(returnedTestValue)) {
+          (<Promise<any>>returnedTestValue).then(null, (err) => { done.fail(err); });
+        } else {
+          done.fail('Error: injectAsync was expected to return a promise, but the ' +
+                    ' returned value was: ' + returnedTestValue);
+        }
+      } else {
+        if (!(returnedTestValue === undefined)) {
+          done.fail('Error: inject returned a value. Did you mean to use injectAsync? Returned ' +
+                    'value was: ' + returnedTestValue);
+        }
+      }
     });
   } else {
     // The test case doesn't use inject(). ie `beforeEach((done) => { ... }));`