Add an addTearDown() function.

See #109
Closes #93

Author: nex3

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## 0.12.18
 
+* Add an `addTearDown()` function, which allows tests to register additional
+  tear-down callbacks as they're running.
+
 * Add the `spawnHybridUri()` and `spawnHybridCode()` functions, which allow
   browser tests to run code on the VM.
 

lib/src/backend/declarer.dart

@@ -105,15 +105,24 @@ class Declarer {
         tags: tags));
 
     _entries.add(new LocalTest(_prefix(name), metadata, () async {
-      // TODO(nweiz): It might be useful to throw an error here if a test starts
-      // running while other tests from the same declarer are also running,
-      // since they might share closurized state.
+      var parents = [];
+      for (var declarer = this; declarer != null; declarer = declarer._parent) {
+        parents.add(declarer);
+      }
+
+      // Register all tear-down functions in all declarers. Iterate through
+      // parents outside-in so that the Invoker gets the functions in the order
+      // they were declared in source.
+      for (var declarer in parents.reversed) {
+        for (var tearDown in declarer._tearDowns) {
+          Invoker.current.addTearDown(tearDown);
+        }
+      }
 
       await Invoker.current.waitForOutstandingCallbacks(() async {
         await _runSetUps();
         await body();
       });
-      await _runTearDowns();
     }, trace: _collectTraces ? new Trace.current(2) : null));
   }
 
@@ -197,23 +206,6 @@ class Declarer {
     await Future.forEach(_setUps, (setUp) => setUp());
   }
 
-  /// Run the tear-up functions for this and any parent groups.
-  ///
-  /// If no set-up functions are declared, this returns a [Future] that
-  /// completes immediately.
-  ///
-  /// This should only be called within a test.
-  Future _runTearDowns() {
-    return Invoker.current.unclosable(() {
-      var tearDowns = [];
-      for (var declarer = this; declarer != null; declarer = declarer._parent) {
-        tearDowns.addAll(declarer._tearDowns.reversed);
-      }
-
-      return Future.forEach(tearDowns, _errorsDontStopTest);
-    });
-  }
-
   /// Returns a [Test] that runs the callbacks in [_setUpAll].
   Test get _setUpAll {
     if (_setUpAlls.isEmpty) return null;
@@ -229,24 +221,8 @@ class Declarer {
 
     return new LocalTest(_prefix("(tearDownAll)"), _metadata, () {
       return Invoker.current.unclosable(() {
-        return Future.forEach(_tearDownAlls.reversed, _errorsDontStopTest);
+        return Future.forEach(_tearDownAlls.reversed, errorsDontStopTest);
       });
     }, trace: _tearDownAllTrace);
   }
-
-  /// Runs [body] with special error-handling behavior.
-  ///
-  /// Errors emitted [body] will still cause the current test to fail, but they
-  /// won't cause it to *stop*. In particular, they won't remove any outstanding
-  /// callbacks registered outside of [body].
-  Future _errorsDontStopTest(body()) {
-    var completer = new Completer();
-
-    Invoker.current.addOutstandingCallback();
-    Invoker.current.waitForOutstandingCallbacks(() {
-      new Future.sync(body).whenComplete(completer.complete);
-    }).then((_) => Invoker.current.removeOutstandingCallback());
-
-    return completer.future;
-  }
 }

lib/src/backend/invoker.dart

@@ -126,11 +126,23 @@ class Invoker {
   /// This will be `null` until the test starts running.
   Timer _timeoutTimer;
 
+  /// The tear-down functions to run when this test finishes.
+  final _tearDowns = new List<AsyncFunction>();
+
   Invoker._(Suite suite, LocalTest test, {Iterable<Group> groups}) {
     _controller = new LiveTestController(
         suite, test, _onRun, _onCloseCompleter.complete, groups: groups);
   }
 
+  /// Runs [callback] after this test completes.
+  ///
+  /// The [callback] may return a [Future]. Like all tear-downs, callbacks are
+  /// run in the reverse of the order they're declared.
+  void addTearDown(callback()) {
+    if (closed) throw new ClosedException();
+    _tearDowns.add(callback);
+  }
+
   /// Tells the invoker that there's a callback running that it should wait for
   /// before considering the test successful.
   ///
@@ -301,13 +313,17 @@ class Invoker {
         // a chance to hit its event handler(s) before the test produces an
         // error. If an error is emitted before the first state change is
         // handled, we can end up with [onError] callbacks firing before the
-        // corresponding [onStateChange], which violates the timing
+        // corresponding [onStateChkange], which violates the timing
         // guarantees.
         //
         // Using [new Future] also avoids starving the DOM or other
         // microtask-level events.
-        new Future(_test._body)
-            .then((_) => removeOutstandingCallback());
+        new Future(() async {
+          await _test._body();
+          await unclosable(() =>
+              Future.forEach(_tearDowns.reversed, errorsDontStopTest));
+          removeOutstandingCallback();
+        });
 
         await _outstandingCallbacks.noOutstandingCallbacks;
         if (_timeoutTimer != null) _timeoutTimer.cancel();

lib/src/utils.dart

@@ -11,6 +11,7 @@ import 'package:async/async.dart' hide StreamQueue;
 import 'package:path/path.dart' as p;
 import 'package:stack_trace/stack_trace.dart';
 
+import 'backend/invoker.dart';
 import 'backend/operating_system.dart';
 import 'util/stream_queue.dart';
 
@@ -347,6 +348,24 @@ void invoke(fn()) {
   fn();
 }
 
+/// Runs [body] with special error-handling behavior.
+///
+/// Errors emitted [body] will still cause the current test to fail, but they
+/// won't cause it to *stop*. In particular, they won't remove any outstanding
+/// callbacks registered outside of [body].
+///
+/// This may only be called within a test.
+Future errorsDontStopTest(body()) {
+  var completer = new Completer();
+
+  Invoker.current.addOutstandingCallback();
+  Invoker.current.waitForOutstandingCallbacks(() {
+    new Future.sync(body).whenComplete(completer.complete);
+  }).then((_) => Invoker.current.removeOutstandingCallback());
+
+  return completer.future;
+}
+
 /// Returns a random base64 string containing [bytes] bytes of data.
 ///
 /// [seed] is passed to [math.Random].

lib/test.dart

@@ -7,6 +7,7 @@ import 'dart:async';
 import 'package:path/path.dart' as p;
 
 import 'src/backend/declarer.dart';
+import 'src/backend/invoker.dart';
 import 'src/backend/test_platform.dart';
 import 'src/frontend/timeout.dart';
 import 'src/runner/configuration/suite.dart';
@@ -228,8 +229,26 @@ void setUp(callback()) => _declarer.setUp(callback);
 ///
 /// Each callback at the top level or in a given group will be run in the
 /// reverse of the order they were declared.
+///
+/// See also [addTearDown], which adds tear-downs to a running test.
 void tearDown(callback()) => _declarer.tearDown(callback);
 
+/// Registers a function to be run after the current test.
+///
+/// This is called within a running test, and adds a tear-down only for the
+/// current test. It allows testing libraries to add cleanup logic as soon as
+/// there's something to clean up.
+///
+/// The [callback] is run before any callbacks registered with [tearDown]. Like
+/// [tearDown], the most recently registered callback is run first.
+void addTearDown(callback()) {
+  if (Invoker.current == null) {
+    throw new StateError("addTearDown() may only be called within a test.");
+  }
+
+  Invoker.current.addTearDown(callback);
+}
+
 /// Registers a function to be run once before all tests.
 ///
 /// [callback] may be asynchronous; if so, it must return a [Future].