More tests and doc for futures (followup to http://codereview.chromium.org/10517006/)

tests/corelib/future_test.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // Tests for Future.immediate
 
 testImmediate() {
   final future = new Future<String>.immediate("42");
   Expect.isTrue(future.isComplete);
   Expect.isTrue(future.hasValue);
@@ skipping 375 matching lines @@
 
 testTransformTransformerFails() {
   final completer = new Completer<String>();
   final error = new Exception("Oh no!");
   final transformedFuture = completer.future.transform((x) { throw error; });
   Expect.isFalse(transformedFuture.isComplete);
   completer.complete("42");
   Expect.equals(error, transformedFuture.exception);
 }
 
+// Tests [handleException] and [transform] on the same Future.
+// An earlier implementation of [transform] didn't support this, and behavior
+// depended on whether [handleException] or [transform] was called first.
+
+testTransformAndHandleException() {
+  final completer = new Completer<String>();
+  final error = new Exception("Oh no!");
+  var futureError;
+  var transformedFutureError;
+
+  completer.future.transform((x) => "** $x **").handleException((e) {
+    Expect.isNotNull(futureError);
+    transformedFutureError = e;
+    return true;
+  });
+  completer.future.handleException((e) {
+    Expect.isNull(transformedFutureError);
+    futureError = e;
+    return true;
+  });
+  completer.completeException(error);
+
+  Expect.equals(error, futureError);
+  Expect.equals(error, transformedFutureError);
+}
+
+testHandleExceptionAndTransform() {
+  final completer = new Completer<String>();
+  final error = new Exception("Oh no!");
+  var futureError;
+  var transformedFutureError;
+
+  completer.future.handleException((e) {
+    Expect.isNull(transformedFutureError);
+    futureError = e;
+    return true;
+  });
+  completer.future.transform((x) => "** $x **").handleException((e) {
+    Expect.isNotNull(futureError);
+    transformedFutureError = e;
+    return true;
+  });
+  completer.completeException(error);
+
+  Expect.equals(error, futureError);
+  Expect.equals(error, transformedFutureError);
+}
+
 // Tests for Future.chain
 
 testChainSuccess() {
   final completerA = new Completer<String>();
   final completerB = new Completer<String>();
   final chainedFuture = completerA.future.chain((x) {
     Expect.equals("42", x);
     return completerB.future;
   });
   Expect.isFalse(chainedFuture.isComplete);
@@ skipping 34 matching lines @@
     Expect.equals("42", x);
     return completerB.future;
   });
   Expect.isFalse(chainedFuture.isComplete);
   completerA.complete("42");
   Expect.isFalse(chainedFuture.isComplete);
   completerB.completeException(error);
   Expect.equals(error, chainedFuture.exception);
 }
 
+// Tests [handleException] and [chain] on the same Future.
+// An earlier implementation of [chain] didn't support this, and behavior
+// depended on whether [handleException] or [chain] was called first.
+
+testChainAndHandleException() {
+  final completer = new Completer<String>();
+  final error = new Exception("Oh no!");
+  var futureError;
+  var chainedFutureError;
+
+  var chainedFuture = completer.future
+      .chain((_) => new Future<int>.immediate(43));
+  chainedFuture.handleException((e) {
+    Expect.isNotNull(futureError);
+    chainedFutureError = e;
+    return true;
+  });
+  completer.future.handleException((e) {
+    Expect.isNull(chainedFutureError);
+    futureError = e;
+    return true;
+  });
+  completer.completeException(error);
+
+  Expect.equals(error, futureError);
+  Expect.equals(error, chainedFutureError);
+}
+
+testHandleExceptionAndChain() {
+  final completer = new Completer<String>();
+  final error = new Exception("Oh no!");
+  var futureError;
+  var chainedFutureError;
+
+  completer.future.handleException((e) {
+    Expect.isNull(chainedFutureError);
+    futureError = e;
+    return true;
+  });
+  var chainedFuture = completer.future
+      .chain((_) => new Future<int>.immediate(43));
+  chainedFuture.handleException((e) {
+    Expect.isNotNull(futureError);
+    chainedFutureError = e;
+    return true;
+  });
+  completer.completeException(error);
+
+  Expect.equals(error, futureError);
+  Expect.equals(error, chainedFutureError);
+}
+
 main() {
   testImmediate();
   testNeverComplete();
   testComplete();
   testCompleteWithCompleteHandlerBeforeComplete();
   testExceptionWithCompleteHandlerBeforeComplete();
   testCompleteWithCompleteHandlerAfterComplete();
   testExceptionWithCompleteHandlerAfterComplete();
   testCompleteWithManyCompleteHandlers();
   testExceptionWithManyCompleteHandlers();
   testCompleteWithSuccessHandlerBeforeComplete();
   testCompleteWithSuccessHandlerAfterComplete();
   testCompleteManySuccessHandlers();
   testException();
   testExceptionHandler();
   testExceptionHandlerReturnsTrue();
   testExceptionHandlerReturnsTrue2();
   testExceptionHandlerReturnsFalse();
   testExceptionHandlerReturnsFalse2();
   testExceptionHandlerAfterCompleteThenNotCalled();
   testExceptionHandlerAfterCompleteReturnsFalseThenThrows();
   testCompleteWithCompletionAndSuccessHandlers();
   testExceptionWithCompletionAndSuccessHandlers();
   testExceptionWithCompletionAndSuccessAndExceptionHandlers();
   testTransformSuccess();
   testTransformFutureFails();
   testTransformTransformerFails();
+  testTransformAndHandleException();
+  testHandleExceptionAndTransform();
   testChainSuccess();
   testChainFirstFutureFails();
   testChainTransformerFails();
   testChainSecondFutureFails();
+  testChainAndHandleException();
+  testHandleExceptionAndChain();
 }