Add a skip parameter to expect().

lib/src/frontend/expect.dart

 // Copyright (c) 2015, 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.
 
 import 'package:matcher/matcher.dart';
 
 import '../backend/closed_exception.dart';
 import '../backend/invoker.dart';
 
 /// An exception thrown when a test assertion fails.
@@ skipping 14 matching lines @@
 ///
 /// This is the main assertion function. [reason] is optional and is typically
 /// not supplied, as a reason is generated from [matcher]; if [reason]
 /// 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.
 ///
+/// If [skip] is a String or `true`, the assertion is skipped. The arguments are
+/// still evaluated, but [actual] is not verified to match [matcher]. If
+/// [actual] is a [Future], the test won't complete until the future emits a
+/// value.
+///
+/// If [skip] is a string, it should explain why the assertion is skipped; this
+/// reason will be printed when running the test.
+///
 /// 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`.
 void expect(actual, matcher,
-    {String reason, bool verbose: false, ErrorFormatter formatter}) {
+    {String reason, skip, bool verbose: false, ErrorFormatter formatter}) {
   if (Invoker.current == null) {
     throw new StateError("expect() may only be called within a test.");
   }
 
   if (Invoker.current.closed) throw new ClosedException();
 
+  if (skip != null && skip is! bool && skip is! String) {
+    throw new ArgumentError.value(skip, "skip", "must be a bool or a String");
+  }
+
   matcher = wrapMatcher(matcher);
+  if (skip != null && skip != false) {
+    String message;
+    if (skip is String) {
+      message = "Skip expect: $skip";
+    } else if (reason != null) {
+      message = "Skip expect ($reason).";
+    } else {
+      var description = new StringDescription().addDescriptionOf(matcher);
+      message = "Skip expect ($description).";
+    }
+
+    Invoker.current.skip(message);
+    return;
+  }
+
   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));
@@ skipping 12 matching lines @@
 
   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();
 }