scheduled_test 0.12.8

A package for writing readable tests of asynchronous behavior.

This package works by building up a queue of asynchronous tasks called a "schedule", then executing those tasks in order. This allows the tests to read like synchronous, linear code, despite executing asynchronously.

The scheduled_test package is built on top of the test package, and should be imported instead of test. It provides its own version of group(), test(), setUp(), and tearDown(), and re-exports most other APIs from test.

To schedule a task, call the schedule() function. For example:

import 'package:scheduled_test/scheduled_test.dart';

void main() {
  test('writing to a file and reading it back should work', () {
    schedule(() {
      // The schedule won't proceed until the returned Future has
      // completed.
      return new File("output.txt").writeAsString("contents");

    schedule(() async {
      var contents = await new File("output.txt").readAsString();

      // The normal unittest matchers can still be used.
      expect(contents, equals("contents"));

Setting up and tearing down #

The scheduled_test package defines its own setUp() method that works just like the one in test. Tasks can be scheduled in setUp(); they'll be run before the tasks scheduled by tests in that group. currentSchedule is also set in the setUp() callback.

Similarly, tasks to run after all the tests in the group can be scheduled using tearDown(). However, the best way to clean up after a test is to add callbacks to the onComplete queue. This queue will always run after the test, whether or not it succeeded. For example:

import 'package:scheduled_test/scheduled_test.dart';

void main() {
  var tempDir;
  setUp(() {
    schedule(() async {
      tempDir = await createTempDir();

    currentSchedule.onComplete.schedule(() => deleteDir(tempDir));

  // ...

Passing values between tasks #

It's often useful to use values computed in one task in other tasks that are scheduled afterwards. There are two ways to do this. The most straightforward is just to define a local variable and assign to it. For example:

import 'package:scheduled_test/scheduled_test.dart';

void main() {
  test('computeValue returns 12', () {
    var value;

    schedule(() async {
      value = await computeValue();

    schedule(() => expect(value, equals(12)));

However, this doesn't scale well, especially when you start factoring out calls to schedule() into library methods. For that reason, schedule() returns a Future that will complete to the same value as the return value of the task. For example:

import 'package:scheduled_test/scheduled_test.dart';

void main() {
  test('computeValue returns 12', () {
    var valueFuture = schedule(() => computeValue());
    schedule(() {
      expect(valueFuture, completion(equals(12)));

0.12.8 #

  • Support scheduling in setUpAll() and tearDownAll().

0.12.7 #

  • Support test version 0.12.17.

0.12.6+1 #

  • Support test version 0.12.16.

0.12.6 #

  • Support test version 0.12.15.

0.12.5+6 #

  • Declare compatibility with test version 0.12.14.

0.12.5+5 #

  • Fix all strong mode warnings.

0.12.5+4 #

  • Actually declare compatibility with test version 0.12.13.

0.12.5+3 #

  • Declare compatibility with test version 0.12.13.

0.12.5+2 #

  • Declare compatibility with test version 0.12.12.

0.12.5+1 #

  • Declare compatibility with test version 0.12.11.

0.12.5 #

  • Add a tags parameter to test() and group().

0.12.4+6 #

  • Declare compatibility with test version 0.12.10.

0.12.4+5 #

  • Declare compatibility with shelf version 0.7.0.

  • Declare compatibility with test version 0.12.9.

0.12.4+4 #

  • Declare compatibility with test version 0.12.8.

0.12.4+3 #

  • Declare compatibility with test version 0.12.7.

0.12.4+2 #

  • Declare compatibility with http_multi_server version 2.0.0.

0.12.4+1 #

  • Update the dependency on test to include 0.12.6.

0.12.4 #

  • Update the dependency on test to include 0.12.5.

0.12.3 #

  • Update the dependency on test to include 0.12.4.

0.12.2 #

  • Add ScheduledServer.handleUnscheduled, which allows users to create long-lasting handlers that aren't part of the test schedule.

  • Support WebSocket connections with ScheduledServers.

0.12.1+2 #

  • Fix running scheduled tests via dart path/to/test.dart.

0.12.1+1 #

  • Fixed usage of timeout in test and group.

0.12.1 #

  • Add named parameters to the wrapper test() and group() methods that forward to the test package.

0.12.0 #

  • When an error occurs in the tasks queue, the onComplete queue will begin running immediately rather than waiting for all outstanding tasks and out-of-band callbacks to complete. This more closely matches the semantics of the underlying test framework and will hopefully be less surprising.

  • Errors are now only converted to ScheduleErrors when they're added to the Schedule.errors list. This means that errors emitted by calls to schedule() will no longer be ScheduleErrors.

  • An error thrown in one task will no longer be emitted by the return values of future calls to schedule().

  • Remove the Schedule.onException queue. This was largely redundant with Schedule.onComplete and complicated the implementation.

  • Remove Schedule.pendingCallbacks and ScheduleError.pendingCallbacks. Printing out the pending callbacks was rarely useful once stack chains existed, so they were just producing visual clutter.

  • Remove Schedule.timeout and Schedule.heartbeat. Timeouts will be handled by the test package instead.

  • Remove Schedule.signalError. Use registerException from the test package instead.

  • Remove wrapFuture, Schedule.wrapFuture, and Schedule.wrapAsync. Use expectAsync, completes, and completion from the test package instead.

  • Remove TaskQueue.onTasksComplete.

0.11.8+1 #

  • Bump the version constraint for unittest.

0.11.8 #

  • Add a ScheduledProcess.signal() method for sending signals to subprocesses.

0.11.7+1 #

  • Support version 0.6.0 of shelf.

0.11.7 #

  • Bumped the version constraint for unittest.

0.11.6 #

  • Actually bump the version constraint for unittest.

0.11.5 #

  • Bump the version constraint for unittest.

0.11.4 #

  • Bump the version constraint for unittest.

0.11.3 #

  • Narrow the constraint on unittest to ensure that new features are reflected in scheduled_test's version.

0.11.2+3 #

  • Ignore hidden files in DirectoryDescriptor.fromFilesystem.

0.11.2+2 #

  • Moved shared test utilities to metatest package.

0.11.2+1 #

  • Fix a case where a ScheduledProcess could fail to log its output.

0.11.2 #

  • Add a DirectoryDescriptor.fromFilesystem constructor.

0.11.1 #

  • Add a top-level tearDown function.

0.11.0+7 #

  • A nothing() descriptor will fail if a broken symlink is present.

0.11.0+6 #

  • Use http_multi_server to bind to both the IPv4 and IPv6 loopback addresses for scheduled_test.

0.11.0+5 #

  • Widen the version constraint for stack_trace.

0.11.0+4 #

  • Added with content from lib/scheduled_test.dart.

  • Made changes to test/metatest.dart related to outstanding issues.

0.11.0+3 #

  • Support v0.11.0 of unittest.

0.11.0+1 #

  • Support v0.5.0 of shelf.

0.11.0 #

  • ScheduledServer.handle now takes a shelf.Handler rather than a custom handler class.

  • The body of a test() or a setUp() call may now return a Future. This was already supported by the unittest package. The Future is passed to a wrapFuture call.

0.10.1+1 #

  • Updated http version constraint from ">=0.9.0 <0.10.0" to ">=0.9.0 <0.11.0"

0.10.1 #

  • Add a StreamMatcher.hasMatch method.

  • The consumeThrough and consumeWhile matchers for ScheduledStream now take StreamMatchers as well as normal Matchers.

0.10.0 #

  • Convert ScheduledProcess to expose stdout and stderr as ScheduledStreams.

  • Add a consumeWhile matcher for ScheduledStream.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  scheduled_test: ^0.12.8

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:scheduled_test/scheduled_test.dart';
Awaiting analysis to complete.