Dart Testing Ecosystem

The dart-lang/test repository contains several specialized packages for testing in Dart and Flutter.

• package:test: The primary, full-featured library for writing and running tests across different platforms. This is the standard choice for most users.
• package:checks: A modern framework for expressing test expectations using a literate API. It is intended as a successor to package:matcher.
• package:matcher: Provides an extensible Matcher class and built-in implementations for common test expectations.
• package:fake_async: Used for deterministic testing by providing fake asynchronous events like timers and microtasks.
• package:test_process: A utility for managing test processes, including starting them, validating stdout/stderr, and checking exit codes.
• package:test_descriptor: An API for defining and verifying file and directory structures.

Note: package:test_api and package:test_core are considered implementation details and are generally not intended for direct use by end-users.

Unlike dart:io which uses binary streams, TestProcess.stdout and TestProcess.stderr emit strings for each line. These are StreamQueues, allowing you to pull lines one by one using the .next getter.

To access the output without consuming the queues, use stdoutStream() or stderrStream(). These methods return a new stream that replays the output from the beginning.

import 'package:test/test.dart';
import 'package:test_process/test_process.dart';

void main() {
  test('pull-based output reading', () async {
    var process = await TestProcess.start('dart', ['pub', 'get']);

    // Pull the first line
    var firstLine = await process.stdout.next;
    expect(firstLine, equals('Resolving dependencies...'));

    // Loop until a specific line is found
    String next;
    do {
      next = await process.stdout.next;
    } while (next != 'Got dependencies!');

    await process.shouldExit(0);
  });
}

You can chain multiple expectations against a single value using Dart's cascade syntax (..). If a chain fails, the output includes descriptions of the expectations that successfully passed before the failure.

Key Composition Utilities:

• Cascade (..): For standard sequential expectations.
• which: Used when a cascade is not possible (e.g., when checking a property like length that returns a non-Subject value).
• has: Used to extract fields or derived values from an object to perform further checks.
• Derived Subjects: Some extensions (like .length) return a new Subject for the derived value, allowing further chaining.

// Using cascade syntax
check(someString)
  ..startsWith('a')
  ..endsWith('z')
  ..contains('lmno');

// Using `which` for properties that don't return a Subject
check(someString).length.which((l) => l
  ..isGreaterThan(10)
  ..isLessThan(100));

// Using `has` to extract and check properties
check(someValue)
  .has((value) => value.property, 'property')
  .equals(expectedPropertyValue);

// Chaining from a derived Subject
check(someString).length.equals(expectedLength);

The test package provides expressive and composable matchers for validating values emitted by a Stream. You can use expectLater() to match against stream events.

Common patterns include:

• Matching a sequence of events with emitsInOrder().
• Matching any one of several possible events with emitsAnyOf().
• Asserting a stream finishes immediately after a match with emitsDone.

Stream matchers can also match StreamQueue objects from the async package. Unlike standard Streams, matching against a StreamQueue allows you to consume specific events while leaving the rest of the queue available for further testing.

import 'dart:async';
import 'package:test/test.dart';

void main() {
  test('process emits status messages', () {
    var stdoutLines = Stream.fromIterable([
      'Ready.',
      'Loading took 150ms.',
      'Succeeded!'
    ]);

    expect(stdoutLines, emitsInOrder([
      'Ready.',
      startsWith('Loading took'),
      emitsAnyOf(['Succeeded!', 'Failed!']),
      emitsDone
    ]));
  });
}