Adds a callback to Future that is invoked upon completion, whether success or failure.

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 18 matching lines @@
   final future = completer.future;
 
   completer.complete(3);
 
   Expect.isTrue(future.isComplete);
   Expect.isTrue(future.hasValue);
   Expect.equals(3, future.value);
   Expect.isNull(future.exception);
 }
 
+// Tests for [onComplete]
+
+testCompleteWithCompleteHandlerBeforeComplete() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+
+  int before;
+  future.onComplete((f) {
+    Expect.equals(future, f);
+    Expect.isTrue(f.isComplete);
+    Expect.isTrue(f.hasValue);
+    before = f.value;
+  });
+  Expect.throws(() => future.value);
+  Expect.isNull(before);
+  completer.complete(3);
+
+  Expect.equals(3, future.value);
+  Expect.equals(3, before);
+}
+
+testExceptionWithCompleteHandlerBeforeComplete() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+  final exception = new Exception();
+
+  var err;
+  future.onComplete((f) {
+    Expect.equals(future, f);
+    Expect.isTrue(f.isComplete);
+    Expect.isFalse(f.hasValue);
+    err = f.exception;
+  });
+  Expect.throws(() => future.exception);
+  Expect.isNull(err);
+  completer.completeException(exception);
+  Expect.equals(exception, future.exception);
+  Expect.equals(exception, err);
+  Expect.throws(() => future.value, check: (e) => e == exception);
+}
+
+testCompleteWithCompleteHandlerAfterComplete() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+
+  int after;
+  completer.complete(3);
+  future.onComplete((f) {
+    Expect.equals(future, f);
+    Expect.isTrue(f.isComplete);
+    Expect.isTrue(f.hasValue);
+    after = f.value;
+  });
+  Expect.equals(3, future.value);
+  Expect.equals(3, after);
+}
+
+testExceptionWithCompleteHandlerAfterComplete() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+  final exception = new Exception();
+
+  var err;
+  completer.completeException(exception);
+  future.onComplete((f) {
+    Expect.equals(future, f);
+    Expect.isTrue(f.isComplete);
+    Expect.isFalse(f.hasValue);
+    err = f.exception;
+  });
+  Expect.equals(exception, future.exception);
+  Expect.equals(exception, err);
+  Expect.throws(() => future.value, check: (e) => e == exception);
+}
+
+testCompleteWithManyCompleteHandlers() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+  int before;
+  int after1;
+  int after2;
+
+  future.onComplete((f) { before = f.value; });
+  completer.complete(3);
+  future.onComplete((f) { after1 = f.value; });
+  future.onComplete((f) { after2 = f.value; });
+
+  Expect.equals(3, future.value);
+  Expect.equals(3, before);
+  Expect.equals(3, after1);
+  Expect.equals(3, after2);
+}
+
+testExceptionWithManyCompleteHandlers() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+  final exception = new Exception();
+  var before;
+  var after1;
+  var after2;
+
+  future.onComplete((f) { before = f.exception; });
+  completer.completeException(exception);
+  future.onComplete((f) { after1 = f.exception; });
+  future.onComplete((f) { after2 = f.exception; });
+
+  Expect.equals(exception, future.exception);
+  Expect.equals(exception, before);
+  Expect.equals(exception, after1);
+  Expect.equals(exception, after2);
+  Expect.throws(() => future.value, check: (e) => e == exception);
+}
+
 // Tests for [then]
 
-testCompleteWithHandlerBeforeComplete() {
+testCompleteWithSuccessHandlerBeforeComplete() {
   final completer = new Completer<int>();
   final future = completer.future;
 
   int before;
   future.then((int v) { before = v; });
   Expect.throws(() { future.value; });
   Expect.isNull(before);
   completer.complete(3);
 
   Expect.equals(3, future.value);
   Expect.equals(3, before);
 }
 
-testCompleteWithHandlerAfterComplete() {
+testCompleteWithSuccessHandlerAfterComplete() {
   final completer = new Completer<int>();
   final future = completer.future;
 
   int after;
   completer.complete(3);
   Expect.equals(3, future.value);
   Expect.isNull(after);
 
   future.then((int v) { after = v; });
 
   Expect.equals(3, future.value);
   Expect.equals(3, after);
 }
 
-testCompleteManyHandlers() {
+testCompleteManySuccessHandlers() {
   final completer = new Completer<int>();
   final future = completer.future;
+  int before;
   int after1;
   int after2;
-  int after3;
 
+  future.then((int v) { before = v; });
+  completer.complete(3);
   future.then((int v) { after1 = v; });
-  completer.complete(3);
   future.then((int v) { after2 = v; });
-  future.then((int v) { after3 = v; });
 
   Expect.equals(3, future.value);
+  Expect.equals(3, before);
   Expect.equals(3, after1);
   Expect.equals(3, after2);
-  Expect.equals(3, after3);
 }
 
 // Tests for [handleException]
 
 testException() {
   final completer = new Completer<int>();
   final future = completer.future;
   final ex = new Exception();
   future.then((_) {}); // exception is thrown if we plan to use the value
   Expect.throws(
       () { completer.completeException(ex); }, 
       check: (e) => e == ex);
 }
 
-testExceptionNoListeners() {
+testExceptionNoSuccessListeners() {
   final completer = new Completer<int>();
   final future = completer.future;
   final ex = new Exception();
   completer.completeException(ex); // future.then is not called, so no exception
 }
 
 testExceptionHandler() {
   final completer = new Completer<int>();
   final future = completer.future;
   final ex = new Exception();
@@ skipping 72 matching lines @@
   final future = completer.future;
   final ex = new Exception();
 
   var ex2;
   completer.completeException(ex);
   future.handleException((e) { ex2 = e; return false; });
   Expect.throws(() { future.then((e) { }); });
   Expect.equals(ex, ex2);
 }
 
+// Tests for mixed usage of [onComplete], [then], and [handleException]
+
+testExceptionWithCompletionAndSuccessHandlers() {

[Jennifer Messerly, 2012/06/04 20:11:17]

it'd be good to have a version of "then" and "onComplete" that doesn't throw,
but verifies ordering. (apologies if I missed it)

[sam.mccall, 2012/06/04 21:35:57]

You didn't; will do.

+  final completer = new Completer<int>();
+  final future = completer.future;
+  final ex = new Exception();
+
+  var exceptionFromCompleteHandler;
+  future.onComplete((f) {
+    Expect.equals(future, f);
+    Expect.isFalse(f.hasValue);
+    exceptionFromCompleteHandler = f.exception;
+  });
+  future.then((v) => Expect.fail("Should not succeed"));
+  Expect.throws(() => completer.completeException(ex), check: (e) => ex == e);
+  Expect.equals(ex, exceptionFromCompleteHandler);
+}
+
+testExceptionWithCompletionAndSuccessAndExceptionHandlers() {
+  final completer = new Completer<int>();
+  final future = completer.future;
+  final ex = new Exception();
+
+  var exceptionFromCompleteHandler;
+  var exceptionFromExceptionHandler;
+  future.onComplete((f) {
+    Expect.equals(future, f);
+    Expect.isFalse(f.hasValue);
+    exceptionFromCompleteHandler = f.exception;
+  });
+  future.handleException((e) {
+    exceptionFromExceptionHandler = e;
+    return true;
+  });
+  future.then((v) => Expect.fail("Should not succeed"));
+  completer.completeException(ex);
+  Expect.equals(ex, exceptionFromCompleteHandler);
+  Expect.equals(ex, exceptionFromExceptionHandler);
+}
+
 // Tests for Future.transform
 
 testTransformSuccess() {
   final completer = new Completer<String>();
   final transformedFuture = completer.future.transform((x) => "** $x **");
   Expect.isFalse(transformedFuture.isComplete);
   completer.complete("42");
   Expect.equals("** 42 **", transformedFuture.value);
 }
 
@@ skipping 68 matching lines @@
   completerA.complete("42");
   Expect.isFalse(chainedFuture.isComplete);
   completerB.completeException(error);
   Expect.equals(error, chainedFuture.exception);
 }
 
 main() {
   testImmediate();
   testNeverComplete();
   testComplete();
-  testCompleteWithHandlerBeforeComplete();
-  testCompleteWithHandlerAfterComplete();
-  testCompleteManyHandlers();
+  testCompleteWithCompleteHandlerBeforeComplete();
+  testExceptionWithCompleteHandlerBeforeComplete();
+  testCompleteWithCompleteHandlerAfterComplete();
+  testExceptionWithCompleteHandlerAfterComplete();
+  testCompleteWithManyCompleteHandlers();
+  testExceptionWithManyCompleteHandlers();
+  testCompleteWithSuccessHandlerBeforeComplete();
+  testCompleteWithSuccessHandlerAfterComplete();
+  testCompleteManySuccessHandlers();
   testException();
   testExceptionHandler();
   testExceptionHandlerReturnsTrue();
   testExceptionHandlerReturnsTrue2();
   testExceptionHandlerReturnsFalse();
   testExceptionHandlerReturnsFalse2();
   testExceptionHandlerAfterCompleteThenNotCalled();
   testExceptionHandlerAfterCompleteReturnsFalseThenThrows();
+  testExceptionWithCompletionAndSuccessHandlers();
+  testExceptionWithCompletionAndSuccessAndExceptionHandlers();
   testTransformSuccess();
   testTransformFutureFails();
   testTransformTransformerFails();
   testChainSuccess();
   testChainFirstFutureFails();
   testChainTransformerFails();
   testChainSecondFutureFails();
 }