New expectation functions plus convert old tests to use these.

lib/unittest/expect.dart

+// Copyright (c) 2012, 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.
+
+/**
+ * This is the main assertion function, and can be used in two ways:
+ *
+ *   expect(value, matcher, reason)

[Bob Nystrom, 2012/05/30 23:23:51]

Do five spaces here and elsewhere. The first one is for the doc comment, and the
other four tell markdown this is a code block.

+ *
+ * or:
+ *
+ *    expect(BooleanConditon, reason)
+ *
+ * The reason is optional and in the first case typically not
+ * supplied, as a reason can be generated from the matcher.
+ *
+ * In the first form expect() asserts that the value [arg1] satisfies
+ * the matcher [arg2] for the reason [arg3]. In the second form expect()

[Bob Nystrom, 2012/05/30 23:23:51]

Do we use the second form anywhere? If not, we could remove it and just require:

    expect(foo, isTrue);

That would let us give nice types for expect(). arg1 is not that user-friendly.

[gram, 2012/06/01 17:33:15]

Done.

+ * asserts that the Boolean condition [arg1] is true for reason [arg2].
+ *
+ * If the assertion fails, then the default behavior is to throw an
+ * ExpectException, but this behavior can be changed by calling

[Bob Nystrom, 2012/05/30 23:23:51]

Put square brackets around ExpectException, configureExpectHandler and
IFailureHandler.

[gram, 2012/06/01 17:33:15]

Done.

+ * configureExpectHandler and providing an alternative handler that
+ * implements the IFailureHandler interface.
+ *
+ * expect is a 3rd generation assertion mechanism, drawing

[Bob Nystrom, 2012/05/30 23:23:51]

`expect()`

[gram, 2012/06/01 17:33:15]

Done.

+ * inspiration from Hamcrest and Ladislav Thon's matcher

[Bob Nystrom, 2012/05/30 23:23:51]

Make these markdown links:

[Hamcrest][] and Ladislav Thon's [dart-matchers][]...

[hamcrest]: http://http://code.google.com/p/hamcrest/
[dart-matchers]: https://github.com/Ladicek/dart-matchers

[gram, 2012/06/01 17:33:15]

Done.

[Bob Nystrom, 2012/06/01 18:22:22]

Almost done. :) The markdown syntax is very specific here. It needs to be:

expect() is a 3rd generation assertion mechanism, drawing
inspiration from [Hamcrest][] and Ladislav Thon's [dart-matchers][]
library.

[Hamcrest]: http://en.wikipedia.org/wiki/Hamcrest
[dart-matchers]: https://github.com/Ladicek/dart-matchers

That will make "Hamcrest" and "dart-matchers" inline links to the provided URLs.

+ * library.
+ *
+ * See http://en.wikipedia.org/wiki/Hamcrest
+ *     http://http://code.google.com/p/hamcrest/
+ *     https://github.com/Ladicek/dart-matchers
+ */
+
+void expect(arg1, [arg2=null, String arg3='']) {
+  if (arg2 is IMatcher) {
+    _assertMatch(arg1, arg2, arg3);
+  } else {
+    _assertBool(arg1, arg2);
+  }
+}
+
+// _assertMatch handles expect() calls that use a matcher.

[Bob Nystrom, 2012/05/30 23:23:51]

This comment is probably not necessary.

[gram, 2012/06/01 17:33:15]

Done.

+// It just checks if the matcher matches, and if not, builds up
+// an error message that then calls the failure handler.
+void _assertMatch(actual, IMatcher matcher, String reason) {
+  if (!matcher.matches(actual)) {
+    // Make sure we have a failure handler and formatter configured
+    configureExpectHandler(_assertFailureHandler);
+    configureExpectFormatter(_assertErrorFormatter);
+    _assertFailureHandler.failMatch(actual, matcher, reason);
+  }
+}
+
+// assertBool handles expect() calls that use a Boolean condition.
+void _assertBool(assertion, [String reason=null]) {

[Bob Nystrom, 2012/05/30 23:23:51]

Type annotate assertion.

[gram, 2012/06/01 17:33:15]

Done.

+  if (!assertion) {
+    if (reason == null) {
+      reason = 'Assertion failed';
+    }
+    // Make sure we have a failure handler configured
+    configureExpectHandler(_assertFailureHandler);
+    _assertFailureHandler.fail(reason);
+  }
+}
+
+// wrapMatcher takes an argument and returns a equivalent matcher.

[Bob Nystrom, 2012/05/30 23:23:51]

"Takes an argument and returns an equivalent matcher."

[gram, 2012/06/01 17:33:15]

Done.

+// If the argument is already a matcher this does nothing, else it
+// generates a equals matcher for the argument.

[Bob Nystrom, 2012/05/30 23:23:51]

"a equals" -> "an equals"

[gram, 2012/06/01 17:33:15]

Done.

+IMatcher wrapMatcher(x) => ((x is IMatcher) ? x : equals(x));

[Bob Nystrom, 2012/05/30 23:23:51]

What is this used for?

[gram, 2012/06/01 17:33:15]

It allows matchers that themselves expect matcher arguments to be passed
scalars. E.g. instead of isNot(equals(3)) you can say isNot(3).

+
+//-----------------------------------------------------------
+// The reference to the failure handler for failed asserts

[Bob Nystrom, 2012/05/30 23:23:51]

This comment doesn't add much.

[gram, 2012/06/01 17:33:15]

Done.

+IFailureHandler _assertFailureHandler = null;
+
+// The default failure handler that throws ExpectExceptions
+class DefaultFailureHandler implements IFailureHandler {
+  void fail(String reason) {
+    throw new ExpectException(reason);
+  }
+  void failMatch(actual, IMatcher matcher, String reason) {
+    fail(_assertErrorFormatter.format(actual, matcher, reason));
+  }
+}
+
+/**
+ * Changes or resets to the default the failure handler for expect()
+ * [handler] is a reference to the new handler (that must implement
+ * IFailureHandler); if this is omitted or null then the failure handler

[Bob Nystrom, 2012/05/30 23:23:51]

Remove "(that must implement IFailureHandler)" That's what type annotations are
for. :)

Also ";" -> "."

[gram, 2012/06/01 17:33:15]

Done.

+ * is reset to the default, which throws ExpectExceptions on expect()

[Bob Nystrom, 2012/05/30 23:23:51]

Square brackets around [ExpectException]s and [expect()].

[gram, 2012/06/01 17:33:15]

Done.

+ * assertion failures.
+ */
+void configureExpectHandler([IFailureHandler handler = null]) {

[Bob Nystrom, 2012/05/30 23:23:51]

Why make this optional?

[gram, 2012/06/01 17:33:15]

For the reset to default case.

+  if (handler == null) {
+    handler = new DefaultFailureHandler();
+  }
+  _assertFailureHandler = handler;
+}
+
+//------------------------------------------------------------------
+// The reference to the error message formatter for failed asserts
+IErrorFormatter _assertErrorFormatter = null;

[Bob Nystrom, 2012/05/30 23:23:51]

This comment doesn't add much.

[gram, 2012/06/01 17:33:15]

Done.

+
+// The default error formatter implementation
+class DefaultErrorFormatter implements IErrorFormatter {
+  String format(actual, IMatcher matcher, String reason) {
+    var description = new StringDescription();
+    description.append(reason).
+    append('\nExpected: ').

[Bob Nystrom, 2012/05/30 23:23:51]

Indent these +4.

[gram, 2012/06/01 17:33:15]

Done.

+    appendDescriptionOf(matcher).
+    append('\n     but: ');
+    matcher.describeMismatch(actual, description);
+    description.append('\n');
+    return description.toString();
+  }
+}
+
+/**
+ * Changes or resets to default the failure message formatter for expect().
+ * [formatter] is a reference to the new formatter (that must implement

[Bob Nystrom, 2012/05/30 23:23:51]

Remove parenthetical.

[gram, 2012/06/01 17:33:15]

Done.

+ * IFailureFormatter); if this is omitted or null then the failure formatter
+ * is reset to the default.
+ */
+void configureExpectFormatter([IErrorFormatter formatter = null]) {
+  if (formatter == null) {
+    formatter = new DefaultErrorFormatter();
+  }
+  _assertErrorFormatter = formatter;
+}
+