Moving main library description to README.md

README.md

Index: README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f9ff2f96a748421b70485c90d598389bc693d3bf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,141 @@
+Support for writing unit tests in Dart.
+
+**See also:**
+[Unit Testing with Dart]
+(http://www.dartlang.org/articles/dart-unit-tests/)
+
+##Concepts
+
+ * __Tests__: Tests are specified via the top-level function [test], they can be
+   organized together using [group].
+
+ * __Checks__: Test expectations can be specified via [expect]
+
+ * __Matchers__: [expect] assertions are written declaratively using the
+   [Matcher] class.
+
+ * __Configuration__: The framework can be adapted by setting
+   [unittestConfiguration] with a [Configuration]. See the other libraries
+   in the `unittest` package for alternative implementations of
+   [Configuration] including `compact_vm_config.dart`, `html_config.dart`
+   and `html_enhanced_config.dart`.
+
+##Examples
+
+A trivial test:
+
+```dart
+import 'package:unittest/unittest.dart';
+
+void main() {
+  test('this is a test', () {
+    int x = 2 + 3;
+    expect(x, equals(5));
+  });
+}
+```
+
+Multiple tests:
+
+```dart
+import 'package:unittest/unittest.dart';
+
+void main() {
+  test('this is a test', () {
+    int x = 2 + 3;
+    expect(x, equals(5));
+  });
+  test('this is another test', () {
+    int x = 2 + 3;
+    expect(x, equals(5));
+  });
+}
+```
+
+Multiple tests, grouped by category:
+
+```dart
+import 'package:unittest/unittest.dart';
+
+void main() {
+  group('group A', () {
+    test('test A.1', () {
+      int x = 2 + 3;
+      expect(x, equals(5));
+    });
+    test('test A.2', () {
+      int x = 2 + 3;
+      expect(x, equals(5));
+    });
+  });
+  group('group B', () {
+    test('this B.1', () {
+      int x = 2 + 3;
+      expect(x, equals(5));
+    });
+  });
+}
+```
+
+Asynchronous tests: if callbacks expect between 0 and 6 positional
+arguments, [expectAsync] will wrap a function into a new callback and will
+not consider the test complete until that callback is run. A count argument
+can be provided to specify the number of times the callback should be called
+(the default is 1).
+
+```dart
+import 'dart:async';
+import 'package:unittest/unittest.dart';
+
+void main() {
+  test('callback is executed once', () {
+    // wrap the callback of an asynchronous call with [expectAsync] if
+    // the callback takes 0 arguments...
+    Timer.run(expectAsync(() {
+      int x = 2 + 3;
+      expect(x, equals(5));
+    }));
+  });
+
+  test('callback is executed twice', () {
+    var callback = expectAsync(() {
+      int x = 2 + 3;
+      expect(x, equals(5));
+    }, count: 2); // <-- we can indicate multiplicity to [expectAsync]
+    Timer.run(callback);
+    Timer.run(callback);
+  });
+}
+```
+
+There may be times when the number of times a callback should be called is
+non-deterministic. In this case a dummy callback can be created with
+expectAsync((){}) and this can be called from the real callback when it is
+finally complete.
+
+A variation on this is [expectAsyncUntil], which takes a callback as the
+first parameter and a predicate function as the second parameter. After each
+time the callback is called, the predicate function will be called. If it
+returns `false` the test will still be considered incomplete.
+
+Test functions can return [Future]s, which provide another way of doing
+asynchronous tests. The test framework will handle exceptions thrown by
+the Future, and will advance to the next test when the Future is complete.
+
+```dart
+import 'dart:async';
+import 'package:unittest/unittest.dart';
+
+void main() {
+  test('test that time has passed', () {
+    var duration = const Duration(milliseconds: 200);
+    var time = new DateTime.now();
+
+    return new Future.delayed(duration).then((_) {
+      var delta = new DateTime.now().difference(time);
+
+      expect(delta, greaterThanOrEqualTo(duration));
+    });
+  });
+}
+```