unittest: refactor ahead of matcher changes

lib/src/expect.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file

[nweiz, 2015/01/26 22:44:09]

Use the current year for copyright headers, even for mostly copy/pasted files.

[kevmoo, 2015/01/27 00:11:29]

Done.

+// 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.
+
+library unittest.expect;
+
+import 'package:matcher/matcher.dart';
+
+/// The objects thrown by the default failure handler.

[nweiz, 2015/01/26 22:44:09]

You removed any concept of a "failure handler".

I'd say "An exception thrown when a test assertion fails."

[kevmoo, 2015/01/27 00:11:30]

Done.

+class TestFailure extends Error {

[nweiz, 2015/01/26 22:44:09]

I don't think this should extend Error. It's not a "program failure that the
programmer should have avoided".

[kevmoo, 2015/01/27 00:11:29]

Done.

+  final String message;
+
+  TestFailure(this.message);
+
+  String toString() => message;
+}
+
+/// The used for functions that can be used to build up error reports upon
+/// failures in [expect].

[nweiz, 2015/01/26 22:44:09]

"The used" -> "The type used"

It seems very strange to have this tied to [expect] rather than the
configuration, but that's something we can deal with later.

[kevmoo, 2015/01/27 00:11:29]

Done.

+typedef String ErrorFormatter(
+    actual, Matcher matcher, String reason, Map matchState, bool verbose);
+
+/// Assert that [actual] matches [matcher].
+///
+/// This is the main assertion function. [reason] is optional and is typically
+/// not supplied, as a reason is generated from the matcher; if [reason]

[nweiz, 2015/01/26 22:44:09]

"the matcher" -> "[matcher]"

[kevmoo, 2015/01/27 00:11:29]

Done.

+/// is included it is appended to the reason generated by the matcher.
+///
+/// [matcher] can be a value in which case it will be wrapped in an
+/// [equals] matcher.
+///
+/// If the assertion fails a [TestFailure] is thrown.
+///
+/// In some cases extra diagnostic info can be produced on failure (for
+/// example, stack traces on mismatched exceptions). To enable these,
+/// [verbose] should be specified as true;

[nweiz, 2015/01/26 22:44:09]

"specified as true;" -> "`true`.".

[kevmoo, 2015/01/27 00:11:29]

Done.

+void expect(actual, matcher,
+    {String reason, bool verbose: false, ErrorFormatter formatter}) {
+  matcher = wrapMatcher(matcher);
+  var matchState = {};
+  try {
+    if (matcher.matches(actual, matchState)) return;
+  } catch (e, trace) {
+    if (reason == null) {
+      reason = '${(e is String) ? e : e.toString()} at $trace';
+    }
+  }
+  if (formatter == null) formatter = _defaultFailFormatter;
+  fail(formatter(actual, matcher, reason, matchState, verbose));
+}
+
+/// Convenience method for throwing a new [TestFailure] with the provided
+/// [message].
+void fail(String message) => throw new TestFailure(message);
+
+// The default error formatter implementation.

[nweiz, 2015/01/26 22:44:09]

"formatter implementation." -> "formatter."

[kevmoo, 2015/01/27 00:11:29]

Done.

+String _defaultFailFormatter(
+    actual, Matcher matcher, String reason, Map matchState, bool verbose) {
+  var description = new StringDescription();
+  description.add('Expected: ').addDescriptionOf(matcher).add('\n');
+  description.add('  Actual: ').addDescriptionOf(actual).add('\n');
+
+  var mismatchDescription = new StringDescription();
+  matcher.describeMismatch(actual, mismatchDescription, matchState, verbose);
+
+  if (mismatchDescription.length > 0) {
+    description.add('   Which: ${mismatchDescription}\n');
+  }
+  if (reason != null) description.add(reason).add('\n');
+  return description.toString();
+}