Minimal Test

Introduction

A minimalist library for writing simple tests. Using this package introduces no further dependencies other than Dart SDK >= 2.12.0. Aimed at testing Dart VM scripts using null-safety features.

For features like test-shuffling, restricting tests to certain platforms, stream-matchers, complex asynchronous tests, it is recommended to use the official package test.

Note: In the context of this package, the functions group and test are merely used to organize and label tests and test-groups. Each call to expect is counted as a test. A test run will complete successfully if all expect-tests are passed and none of the test files exits abnormally.

Usage

1. Include minimal_test as a dev_dependency in your pubspec.yaml file.

2. Write unit tests using the functions:

• group: Used to label a group of tests. The argument body, a function returning void or FutureOr<void>, usually contains one or several calls to test.
• test: The body of this function usually contains one or several calls to expect.
• setUpAll: A callback that is run before the body of test.
• tearDownAll: A callback that is run after the body of test has finished.
• expect: Compares two objects. An expect-test is considered passed if the two objects match. (Matching should be understood as a form of lax equality test. For example, two lists match if their entries match, however two empty list with different runtime types do not match. For more information see matcher_test.dart).

import 'package:minimal_test/minimal_test.dart';

/// Custom object
class A {
  A(this.msg);
  final String msg;

  @override
  String toString() {
    return 'A: $msg';
  }
}

/// Custom matcher for class A.
bool isMatchingA(left, right){
  if (left is! A || right is! A) return false;
  return left.msg == right.msg;
}

void main() {
  final a1 = A('a1');
  final a1_copy = a1;
  final a2 = A('a2');
  final a3 = A('a1');

  group('Group of tests', () {
    test('Comparing copies', () {
      expect(a1, a1_copy); // Pass.
    });
    test('Comparing different objects', () {
      expect(a1, a2, 'Expected to fail.'); // Fail.
    });
    test('Using custom matcher function', () {
      expect(a1, a3, isMatching: isMatching); // Pass.
    });

  });
}

3. Run the tests in the package test folder by navigating to the package root and issuing the command:

$ pub run minimal_test:minimal_test.dart

Alternatively, the path to a test file or test directory may be specified:

$ pub run minimal_test:minimal_test.dart example/bin/example_test.dart

Features

• The function expect() has the optional parameter precision enabling approximate matching of objects of type num. The default value of precision is 1.0e-12.

  // Returns true.
  match(1, 0.999999999999);
  // Test passed.
  expect(1, 0.999999999999);

  // Returns false.
  match(1.0, 0.9999);
  // Test failed.
  expect(1.0, 0.9999);

  // Returns true.
  match(1.0. 0.9999, precision: 1e-3);
  // Test passed.
  expect(1.0, 0.9999, precision: 1e-3);

• Iterables and maps are matched in a recursive fashion. The types of the two objects have to match. For example a Set does not match a List even if they have identical entries.

  // Test passed.
  expect([1.0, 2.0, 3.0], [1.0 - 1.0e-14, 2.0, 3.0]);

  // Test failed
  expect(<int>[1, 2], <double>[1.0, 2.0])

  // Test passed.
  expect({ 1: [10, 11], 2: [12, 13]},
         { 1: [10, 11], 2: [12, 13]},
        );

Limitations

To keep the library as simple as possible, test files are not parsed and there is no provision to generate and inspect a node-structure of test-groups and tests. As such, shuffling of tests is currently not supported.

While it is possible to run asynchronous tests, it is recommended to await the completion of the objects being tested before issuing a call to group, test, and expect. Otherwise, the output printed by the method expect might not occur on the right line making it difficult to read the test output. However, the total number of failed/passed tests is reported correctly.

File async_test.dart shows how to test the result of a future calculation.

Features and bugs

Please file feature requests and bugs at the issue tracker.