feat(tests): manage asynchronous tests using zones

Instead of using injectAsync and returning a promise, use the `async` function
to wrap tests. This will run the test inside a zone which does not complete
the test until all asynchronous tasks have been completed.

`async` may be used with the `inject` function, or separately.

BREAKING CHANGE:

`injectAsync` is now deprecated. Instead, use the `async` function
to wrap any asynchronous tests.

Before:
```
it('should wait for returned promises', injectAsync([FancyService], (service) => {
  return service.getAsyncValue().then((value) => { expect(value).toEqual('async value'); });
}));

it('should wait for returned promises', injectAsync([], () => {
  return somePromise.then(() => { expect(true).toEqual(true); });
}));
```

After:
```
it('should wait for returned promises', async(inject([FancyService], (service) => {
  service.getAsyncValue().then((value) => { expect(value).toEqual('async value'); });
})));

// Note that if there is no injection, we no longer need `inject` OR `injectAsync`.
it('should wait for returned promises', async(() => {
  somePromise.then() => { expect(true).toEqual(true); });
}));
```

Author: juliemr

karma-js.conf.js

@@ -20,6 +20,7 @@ module.exports = function(config) {
       'node_modules/zone.js/dist/zone.js',
       'node_modules/zone.js/dist/long-stack-trace-zone.js',
       'node_modules/zone.js/dist/jasmine-patch.js',
+      'node_modules/zone.js/dist/async-test.js',
 
       // Including systemjs because it defines `__eval`, which produces correct stack traces.
       'modules/angular2/src/testing/shims_for_IE.js',

modules/angular2/src/testing/test_injector.ts

@@ -130,6 +130,7 @@ export class InjectSetupWrapper {
     return new FunctionWithParamTokens(tokens, fn, false, this._providers);
   }
 
+  /** @Deprecated {use async(withProviders().inject())} */
   injectAsync(tokens: any[], fn: Function): FunctionWithParamTokens {
     return new FunctionWithParamTokens(tokens, fn, true, this._providers);
   }
@@ -140,6 +141,8 @@ export function withProviders(providers: () => any) {
 }
 
 /**
+ * @Deprecated {use async(inject())}
+ *
  * Allows injecting dependencies in `beforeEach()` and `it()`. The test must return
  * a promise which will resolve when all asynchronous activity is complete.
  *
@@ -161,6 +164,32 @@ export function injectAsync(tokens: any[], fn: Function): FunctionWithParamToken
   return new FunctionWithParamTokens(tokens, fn, true);
 }
 
+/**
+ * Wraps a test function in an asynchronous test zone. The test will automatically
+ * complete when all asynchronous calls within this zone are done. Can be used
+ * to wrap an {@link inject} call.
+ *
+ * Example:
+ *
+ * ```
+ * it('...', async(inject([AClass], (object) => {
+ *   object.doSomething.then(() => {
+ *     expect(...);
+ *   })
+ * });
+ * ```
+ */
+export function async(fn: Function | FunctionWithParamTokens): FunctionWithParamTokens {
+  if (fn instanceof FunctionWithParamTokens) {
+    fn.isAsync = true;
+    return fn;
+  } else if (fn instanceof Function) {
+    return new FunctionWithParamTokens([], fn, true);
+  } else {
+    throw new BaseException('argument to async must be a function or inject(<Function>)');
+  }
+}
+
 function emptyArray(): Array<any> {
   return [];
 }

modules/angular2/src/testing/testing.ts

@@ -9,12 +9,13 @@ import {bind} from 'angular2/core';
 import {
   FunctionWithParamTokens,
   inject,
+  async,
   injectAsync,
   TestInjector,
   getTestInjector
 } from './test_injector';
 
-export {inject, injectAsync} from './test_injector';
+export {inject, async, injectAsync} from './test_injector';
 
 export {expect, NgMatchers} from './matchers';
 
@@ -122,37 +123,28 @@ export function beforeEachProviders(fn): void {
   });
 }
 
+function runInAsyncTestZone(fnToExecute, finishCallback: Function, failCallback: Function,
+                            testName = ''): any {
+  var AsyncTestZoneSpec = Zone['AsyncTestZoneSpec'];
+  var testZoneSpec = new AsyncTestZoneSpec(finishCallback, failCallback, testName);
+  var testZone = Zone.current.fork(testZoneSpec);
+  return testZone.run(fnToExecute);
+}
+
 function _isPromiseLike(input): boolean {
   return input && !!(input.then);
 }
 
 function _it(jsmFn: Function, name: string, testFn: FunctionWithParamTokens | AnyTestFn,
              testTimeOut: number): void {
   var timeOut = testTimeOut;
-
   if (testFn instanceof FunctionWithParamTokens) {
     let testFnT = testFn;
     jsmFn(name, (done) => {
-      var returnedTestValue;
-      try {
-        returnedTestValue = testInjector.execute(testFnT);
-      } catch (err) {
-        done.fail(err);
-        return;
-      }
-
       if (testFnT.isAsync) {
-        if (_isPromiseLike(returnedTestValue)) {
-          (<Promise<any>>returnedTestValue).then(() => { done(); }, (err) => { done.fail(err); });
-        } else {
-          done.fail('Error: injectAsync was expected to return a promise, but the ' +
-                    ' returned value was: ' + returnedTestValue);
-        }
+        runInAsyncTestZone(() => testInjector.execute(testFnT), done, done.fail, name);
       } else {
-        if (!(returnedTestValue === undefined)) {
-          done.fail('Error: inject returned a value. Did you mean to use injectAsync? Returned ' +
-                    'value was: ' + returnedTestValue);
-        }
+        testInjector.execute(testFnT);
         done();
       }
     }, timeOut);
@@ -166,8 +158,6 @@ function _it(jsmFn: Function, name: string, testFn: FunctionWithParamTokens | An
  * Wrapper around Jasmine beforeEach function.
  *
  * beforeEach may be used with the `inject` function to fetch dependencies.
- * The test will automatically wait for any asynchronous calls inside the
- * injected test function to complete.
  *
  * See http://jasmine.github.io/ for more details.
  *
@@ -181,26 +171,10 @@ export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
     // }));`
     let fnT = fn;
     jsmBeforeEach((done) => {
-
-      var returnedTestValue;
-      try {
-        returnedTestValue = testInjector.execute(fnT);
-      } catch (err) {
-        done.fail(err);
-        return;
-      }
       if (fnT.isAsync) {
-        if (_isPromiseLike(returnedTestValue)) {
-          (<Promise<any>>returnedTestValue).then(() => { done(); }, (err) => { done.fail(err); });
-        } else {
-          done.fail('Error: injectAsync was expected to return a promise, but the ' +
-                    ' returned value was: ' + returnedTestValue);
-        }
+        runInAsyncTestZone(() => testInjector.execute(fnT), done, done.fail, 'beforeEach');
       } else {
-        if (!(returnedTestValue === undefined)) {
-          done.fail('Error: inject returned a value. Did you mean to use injectAsync? Returned ' +
-                    'value was: ' + returnedTestValue);
-        }
+        testInjector.execute(fnT);
         done();
       }
     });
@@ -217,10 +191,8 @@ export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
 /**
  * Define a single test case with the given test name and execution function.
  *
- * The test function can be either a synchronous function, an asynchronous function
- * that takes a completion callback, or an injected function created via {@link inject}
- * or {@link injectAsync}. The test will automatically wait for any asynchronous calls
- * inside the injected test function to complete.
+ * The test function can be either a synchronous function, the result of {@link async},
+ * or an injected function created via {@link inject}.
  *
  * Wrapper around Jasmine it function. See http://jasmine.github.io/ for more details.
  *

modules/angular2/test/testing/testing_public_browser_spec.dart

@@ -0,0 +1,7 @@
+library angular2.test.testing.testing_browser_pec;
+
+/**
+ * This is intentionally left blank. The public test lib is only for TS/JS
+ * apps.
+ */
+main() {}

modules/angular2/test/testing/testing_public_browser_spec.ts

@@ -0,0 +1,166 @@
+import {
+  it,
+  iit,
+  xit,
+  describe,
+  ddescribe,
+  xdescribe,
+  expect,
+  beforeEach,
+  beforeEachProviders,
+  inject,
+  async,
+  TestComponentBuilder,
+  fakeAsync,
+  tick
+} from 'angular2/testing';
+
+import {Injectable, bind} from 'angular2/core';
+import {Directive, Component, ViewMetadata} from 'angular2/core';
+import {PromiseWrapper} from 'angular2/src/facade/promise';
+import {XHR} from 'angular2/src/compiler/xhr';
+import {XHRImpl} from 'angular2/src/platform/browser/xhr_impl';
+
+// Components for the tests.
+class FancyService {
+  value: string = 'real value';
+  getAsyncValue() { return Promise.resolve('async value'); }
+  getTimeoutValue() {
+    return new Promise((resolve, reject) => { setTimeout(() => {resolve('timeout value')}, 10); })
+  }
+}
+
+@Component({
+  selector: 'external-template-comp',
+  templateUrl: '/base/modules/angular2/test/testing/static_assets/test.html'
+})
+class ExternalTemplateComp {
+}
+
+@Component({selector: 'bad-template-comp', templateUrl: 'non-existant.html'})
+class BadTemplateUrl {
+}
+
+// Tests for angular2/testing bundle specific to the browser environment.
+// For general tests, see test/testing/testing_public_spec.ts.
+export function main() {
+  describe('test APIs for the browser', () => {
+    describe('angular2 jasmine matchers', () => {
+      describe('toHaveCssClass', () => {
+        it('should assert that the CSS class is present', () => {
+          var el = document.createElement('div');
+          el.classList.add('matias');
+          expect(el).toHaveCssClass('matias');
+        });
+
+        it('should assert that the CSS class is not present', () => {
+          var el = document.createElement('div');
+          el.classList.add('matias');
+          expect(el).not.toHaveCssClass('fatias');
+        });
+      });
+
+      describe('toHaveCssStyle', () => {
+        it('should assert that the CSS style is present', () => {
+          var el = document.createElement('div');
+          expect(el).not.toHaveCssStyle('width');
+
+          el.style.setProperty('width', '100px');
+          expect(el).toHaveCssStyle('width');
+        });
+
+        it('should assert that the styles are matched against the element', () => {
+          var el = document.createElement('div');
+          expect(el).not.toHaveCssStyle({width: '100px', height: '555px'});
+
+          el.style.setProperty('width', '100px');
+          expect(el).toHaveCssStyle({width: '100px'});
+          expect(el).not.toHaveCssStyle({width: '100px', height: '555px'});
+
+          el.style.setProperty('height', '555px');
+          expect(el).toHaveCssStyle({height: '555px'});
+          expect(el).toHaveCssStyle({width: '100px', height: '555px'});
+        });
+      });
+    });
+
+    describe('using the async helper', () => {
+      var actuallyDone: boolean;
+
+      beforeEach(() => { actuallyDone = false; });
+
+      afterEach(() => { expect(actuallyDone).toEqual(true); });
+
+      it('should run async tests with XHRs', async(() => {
+           var xhr = new XHRImpl();
+           xhr.get('/base/modules/angular2/test/testing/static_assets/test.html')
+               .then(() => { actuallyDone = true; });
+         }),
+         10000);  // Long timeout here because this test makes an actual XHR.
+    });
+
+    describe('using the test injector with the inject helper', () => {
+      describe('setting up Providers', () => {
+        beforeEachProviders(() => [bind(FancyService).toValue(new FancyService())]);
+
+        it('provides a real XHR instance',
+           inject([XHR], (xhr) => { expect(xhr).toBeAnInstanceOf(XHRImpl); }));
+
+        it('should allow the use of fakeAsync',
+           inject([FancyService], fakeAsync((service) => {
+                    var value;
+                    service.getAsyncValue().then(function(val) { value = val; });
+                    tick();
+                    expect(value).toEqual('async value');
+                  })));
+      });
+    });
+
+    describe('errors', () => {
+      var originalJasmineIt: any;
+
+      var patchJasmineIt = () => {
+        var deferred = PromiseWrapper.completer();
+        originalJasmineIt = jasmine.getEnv().it;
+        jasmine.getEnv().it = (description: string, fn) => {
+          var done = () => { deferred.resolve() };
+          (<any>done).fail = (err) => { deferred.reject(err) };
+          fn(done);
+          return null;
+        };
+        return deferred.promise;
+      };
+
+      var restoreJasmineIt = () => { jasmine.getEnv().it = originalJasmineIt; };
+
+      it('should fail when an XHR fails', (done) => {
+        var itPromise = patchJasmineIt();
+
+        it('should fail with an error from a promise',
+           async(inject([TestComponentBuilder],
+                        (tcb) => { return tcb.createAsync(BadTemplateUrl); })));
+
+        itPromise.then(() => { done.fail('Expected test to fail, but it did not'); }, (err) => {
+          expect(err).toEqual('Uncaught (in promise): Failed to load non-existant.html');
+          done();
+        });
+        restoreJasmineIt();
+      }, 10000);
+    });
+
+    describe('test component builder', function() {
+      it('should allow an external templateUrl',
+         async(inject([TestComponentBuilder],
+                      (tcb: TestComponentBuilder) => {
+
+                        tcb.createAsync(ExternalTemplateComp)
+                            .then((componentFixture) => {
+                              componentFixture.detectChanges();
+                              expect(componentFixture.debugElement.nativeElement)
+                                  .toHaveText('from external template\n');
+                            });
+                      })),
+         10000);  // Long timeout here because this test makes an actual XHR, and is slow on Edge.
+    });
+  });
+}