Add reason parameter to waitFor.

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.1.0-wip
+
+* Add a `reason` argument to `Clock.waitFor`.
+
 ## 3.0.4
 
 * Require Dart 3.1.

lib/support/async.dart

@@ -14,7 +14,7 @@
 
 import 'dart:async' show Completer, FutureOr;
 
-import 'package:matcher/matcher.dart' as m;
+import 'package:matcher/expect.dart' as m;
 import 'package:stack_trace/stack_trace.dart' show Chain;
 
 const defaultInterval = Duration(milliseconds: 500);
@@ -25,9 +25,10 @@ const clock = Clock();
 Future<T> waitFor<T>(FutureOr<T> Function() condition,
         {Object? matcher,
         Duration timeout = defaultTimeout,
-        Duration interval = defaultInterval}) =>
+        Duration interval = defaultInterval,
+        String? reason}) =>
     clock.waitFor<T>(condition,
-        matcher: matcher, timeout: timeout, interval: interval);
+        matcher: matcher, timeout: timeout, interval: interval, reason: reason);
 
 class Clock {
   const Clock();
@@ -47,17 +48,22 @@ class Clock {
   /// is returned. Otherwise, if [condition] throws, then that exception is
   /// rethrown. If [condition] doesn't throw then an [expect] exception is
   /// thrown.
+  ///
+  /// [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.
   Future<T> waitFor<T>(FutureOr<T> Function() condition,
       {Object? matcher,
       Duration timeout = defaultTimeout,
-      Duration interval = defaultInterval}) async {
+      Duration interval = defaultInterval,
+      String? reason}) async {
     final mMatcher = matcher == null ? null : m.wrapMatcher(matcher);
     final endTime = now.add(timeout);
     while (true) {
       try {
         final value = await condition();
         if (mMatcher != null) {
-          _matcherExpect(value, mMatcher);
+          _matcherExpect(value, mMatcher, reason);
         }
         return value;
       } catch (e) {
@@ -71,7 +77,7 @@ class Clock {
   }
 }
 
-void _matcherExpect(Object? value, m.Matcher matcher) {
+void _matcherExpect(Object? value, m.Matcher matcher, String? reason) {
   final matchState = {};
   if (matcher.matches(value, matchState)) {
     return;
@@ -89,7 +95,12 @@ void _matcherExpect(Object? value, m.Matcher matcher) {
   if (mismatchDescription.length > 0) {
     desc.add('   Which: $mismatchDescription\n');
   }
-  throw Exception(desc.toString());
+
+  if (reason != null) {
+    desc.add('$reason\n');
+  }
+
+  m.fail(desc.toString());
 }
 
 class Lock {

pubspec.yaml

@@ -1,5 +1,5 @@
 name: webdriver
-version: 3.0.4
+version: 3.1.0-wip
 description: >-
   Provides WebDriver bindings for Dart. Supports WebDriver JSON interface and
   W3C spec. Requires the use of WebDriver remote server.

test/support/async_test.dart

@@ -106,7 +106,7 @@ void main() {
       expect(result, equals('Google'));
     });
 
-    test('throws if condition throws and timeouts', () async {
+    test('throws if condition throws', () async {
       Object? exception;
 
       try {
@@ -127,6 +127,20 @@ void main() {
       expect(exception, isNotNull);
     });
 
+    test('throws with passed reason if condition never matches', () async {
+      Object? exception;
+      try {
+        await clock.waitFor(() => null,
+            matcher: isNotNull, reason: 'some reason');
+      } catch (e) {
+        exception = e;
+      }
+      expect(
+          exception,
+          isA<TestFailure>()
+              .having((e) => e.message, 'message', contains('some reason')));
+    });
+
     test('uses Future value', () async {
       final result = await clock.waitFor(() => Future.value('a value'),
           matcher: 'a value');