pkg/scheduled_test/lib/scheduled_test.dart

// Copyright (c) 2013, 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.

// TODO(nweiz): Add support for calling [schedule] while the schedule is already
// running.
// TODO(nweiz): Port the non-Pub-specific scheduled test libraries from Pub.
library scheduled_test;

import 'dart:async';

import 'package:stack_trace/stack_trace.dart';
import 'package:unittest/unittest.dart' as unittest;

import 'src/schedule.dart';
import 'src/schedule_error.dart';

export 'package:unittest/unittest.dart' hide
    test, solo_test, group, setUp, tearDown, completes, completion;

export 'src/schedule.dart';
export 'src/schedule_error.dart';
export 'src/scheduled_future_matchers.dart';
export 'src/task.dart';

/// The [Schedule] for the current test. This is used to add new tasks and
/// inspect the state of the schedule.
///
/// This is `null` when there's no test currently running.
Schedule get currentSchedule => _currentSchedule;
Schedule _currentSchedule;

/// The user-provided set-up function for the currently-running test.
///
/// This is set for each test during `unittest.setUp`.
Function _setUpFn;

/// The user-provided tear-down function for the currently-running test.
///
/// This is set for each test during `unittest.setUp`.
Function _tearDownFn;

/// The user-provided set-up function for the current test scope.
Function _setUpForGroup;

/// The user-provided tear-down function for the current test scope.
Function _tearDownForGroup;

/// Creates a new test case with the given description and body.
///
/// This has the same semantics as [unittest.test].
///
/// If [body] returns a [Future], that future will automatically be wrapped with
/// [wrapFuture].
void test(String description, body()) =>
  _test(description, body, unittest.test);

/// Creates a new test case with the given description and body that will be the
/// only test run in this file.
///
/// This has the same semantics as [unittest.solo_test].
///
/// If [body] returns a [Future], that future will automatically be wrapped with
/// [wrapFuture].
void solo_test(String description, body()) =>
  _test(description, body, unittest.solo_test);

void _test(String description, body(), Function testFn) {
  maybeWrapFuture(future, description) {
    if (future != null) wrapFuture(future, description);
  }

  unittest.ensureInitialized();
  _initializeForGroup();
  testFn(description, () {
    var completer = new Completer();

    // Capture this in a local variable in case we capture an out-of-band error
    // after the schedule completes.
    var errorHandler;

    Chain.capture(() {
      _currentSchedule = new Schedule();
      errorHandler = _currentSchedule.signalError;
      return currentSchedule.run(() {
        if (_setUpFn != null) maybeWrapFuture(_setUpFn(), "set up");
        maybeWrapFuture(body(), "test body");
        if (_tearDownFn != null) maybeWrapFuture(_tearDownFn(), "tear down");
      }).catchError((error, stackTrace) {
        if (error is ScheduleError) {
          assert(error.schedule.errors.contains(error));
          assert(error.schedule == currentSchedule);
          unittest.registerException(error.schedule.errorString());
        } else {
          unittest.registerException(error, new Chain.forTrace(stackTrace));
        }
      }).then(completer.complete);
    }, onError: (error, stackTrace) => errorHandler(error, stackTrace));

    return completer.future;
  });
}

/// Whether or not the tests currently being defined are in a group. This is
/// only true when defining tests, not when executing them.
bool _inGroup = false;

/// Creates a new named group of tests. This has the same semantics as
/// [unittest.group].
void group(String description, void body()) {
  unittest.ensureInitialized();
  _initializeForGroup();
  unittest.group(description, () {
    var oldSetUp = _setUpForGroup;
    var oldTearDown = _tearDownForGroup;
    var wasInitializedForGroup = _initializedForGroup;
    var wasInGroup = _inGroup;
    _setUpForGroup = null;
    _tearDownForGroup = null;
    _initializedForGroup = false;
    _inGroup = true;
    body();
    _setUpForGroup = oldSetUp;
    _tearDownForGroup = oldTearDown;
    _initializedForGroup = wasInitializedForGroup;
    _inGroup = wasInGroup;
  });
}

/// Schedules a task, [fn], to run asynchronously as part of the main task queue
/// of [currentSchedule]. Tasks will be run in the order they're scheduled. If
/// [fn] returns a [Future], tasks after it won't be run until that [Future]
/// completes.
///
/// The return value will be completed once the scheduled task has finished
/// running. Its return value is the same as the return value of [fn], or the
/// value it completes to if it's a [Future].
///
/// If [description] is passed, it's used to describe the task for debugging
/// purposes when an error occurs.
///
/// If this is called when a task queue is currently running, it will run [fn]
/// on the next event loop iteration rather than adding it to a queue. The
/// current task will not complete until [fn] (and any [Future] it returns) has
/// finished running. Any errors in [fn] will automatically be handled.
Future schedule(fn(), [String description]) =>
  currentSchedule.tasks.schedule(fn, description);

/// Register a [setUp] function for a test [group].
///
/// This has the same semantics as [unittest.setUp]. Tasks may be scheduled
/// using [schedule] within [setUpFn], and [currentSchedule] may be accessed as
/// well.
void setUp(setUpFn()) {
  _setUpForGroup = setUpFn;
}

/// Register a [tearDown] function for a test [group].
///
/// This has the same semantics as [unittest.tearDown]. Tasks may be scheduled
/// using [schedule] within [tearDownFn], and [currentSchedule] may be accessed
/// as well. Note that [tearDownFn] will be run synchronously after the test
/// body finishes running, which means it will run before any scheduled tasks
/// have begun.
///
/// To run code after the schedule has finished running, use
/// `currentSchedule.onComplete.schedule`.
void tearDown(tearDownFn()) {
  _tearDownForGroup = tearDownFn;
}

/// Whether [_initializeForGroup] has been called in this group scope.
bool _initializedForGroup = false;

/// Registers callbacks for [unittest.setUp] and [unittest.tearDown] that set up
/// and tear down the scheduled test infrastructure and run the user's [setUp]
/// and [tearDown] callbacks.
void _initializeForGroup() {
  if (_initializedForGroup) return;
  _initializedForGroup = true;

  var setUpFn = _setUpForGroup;
  var tearDownFn = _tearDownForGroup;

  if (_inGroup) {
    unittest.setUp(() => _addSetUpTearDown(setUpFn, tearDownFn));
    return;
  }

  var oldWrapAsync = unittest.wrapAsync;
  unittest.setUp(() {
    if (currentSchedule != null) {
      throw new StateError('There seems to be another scheduled test '
          'still running.');
    }

    unittest.wrapAsync = (f, [description]) {
      // It's possible that this setup is run before a vanilla unittest test
      // if [unittest.test] is run in the same context as
      // [scheduled_test.test]. In that case, [currentSchedule] will never be
      // set and we should forward to the [unittest.wrapAsync].
      if (currentSchedule == null) return oldWrapAsync(f, description);
      return currentSchedule.wrapAsync(f, description);
    };

    _addSetUpTearDown(setUpFn, tearDownFn);
  });

  unittest.tearDown(() {
    unittest.wrapAsync = oldWrapAsync;
    _currentSchedule = null;
    _setUpFn = null;
    _tearDownFn = null;
  });
}

/// Set [_setUpFn] and [_tearDownFn] appropriately.
void _addSetUpTearDown(void setUpFn(), void tearDownFn()) {
  if (setUpFn != null) {
    if (_setUpFn != null) {
      var parentFn = _setUpFn;
      _setUpFn = () { parentFn(); setUpFn(); };
    } else {
      _setUpFn = setUpFn;
    }
  }

  if (tearDownFn != null) {
    if (_tearDownFn != null) {
      var parentFn = _tearDownFn;
      _tearDownFn = () { parentFn(); tearDownFn(); };
    } else {
      _tearDownFn = tearDownFn;
    }
  }
}

/// Like [wrapAsync], this ensures that the current task queue waits for
/// out-of-band asynchronous code, and that errors raised in that code are
/// handled correctly. However, [wrapFuture] wraps a [Future] chain rather than
/// a single callback.
///
/// The returned [Future] completes to the same value or error as [future].
///
/// [description] provides an optional description of the future, which is
/// used when generating error messages.
Future wrapFuture(Future future, [String description]) {
  if (currentSchedule == null) {
    throw new StateError("Unexpected call to wrapFuture with no current "
        "schedule.");
  }

  return currentSchedule.wrapFuture(future, description);
}