Rename matches to matchesPattern, accept Pattern (#1907)

This will treat a `String` argument differently from the equivalent
matcher in `package:matcher`, which would have converted strings to
regex. Document this in the migration guide.

Add tests showing the behavior of passing strings, and explicitly choose
cases that show the argument is not treated as a regular expression.

Expand the doc comment and show examples of both types of arguments.

Author: natebosch

pkgs/checks/CHANGELOG.md

@@ -11,8 +11,8 @@
     -   `nestAsync` no longer returns a `Subject`, callers must pass the
         followup `Condition` to the nullable argument.
     -   Remove the `which` extension on `Future<Subject>`.
--   Add a constructor for `Condition` which takes a callback to invoke when
-    `apply` or `applyAsync` is called.
+    -   `matches` renamed to `matchesPattern` and now accepts a `Pattern`
+        argument, instead of limiting to `RegExp`.
 -   Added an example.
 -   Include a stack trace in the failure description for unexpected errors from
     Futures or Streams.

pkgs/checks/doc/migrating_from_matcher.md

@@ -66,6 +66,17 @@ check(actualCollection).deepEquals(expected);
     value to check for equality, a matcher for the emitted value, or a matcher
     for the entire queue which would match multiple values. Use `it()..emits()`
     to check the emitted elements.
+-   In `package:matcher` the [`matches` Matcher][matches] converted a `String`
+    argument into a `Regex`, so `matches(r'\d')` would match the value `'1'`.
+    This was potentially confusing, because even though `String` is a subtype of
+    `Pattern`, it wasn't used as a pattern directly.
+    With `matchesPattern` a `String` argument is used as a `Pattern` and
+    comparison uses [`String.allMatches`][allMatches].
+    For backwards compatibility change `matches(regexString)` to
+    `matchesPattern(RegExp(regexString))`.
+
+[matches]:https://pub.dev/documentation/matcher/latest/matcher/Matcher/matches.html
+[allMatches]:https://api.dart.dev/stable/2.19.1/dart-core/Pattern/allMatches.html
 
 ## Matchers with replacements under a different name
 

pkgs/checks/lib/src/extensions/string.dart

@@ -59,10 +59,18 @@ extension StringChecks on Subject<String> {
     );
   }
 
-  /// Expects that the string matches the regular expression [expected].
-  void matches(RegExp expected) {
+  /// Expects that the string matches the pattern [expected].
+  ///
+  /// Fails if [expected] returns an empty result from calling `allMatches` with
+  /// the value.
+  ///
+  /// ```
+  /// check(actual).matchesPattern('abc');
+  /// check(actual).matchesPattern(RegExp(r'\d'));
+  /// ```
+  void matchesPattern(Pattern expected) {
     context.expect(() => prefixFirst('matches ', literal(expected)), (actual) {
-      if (expected.hasMatch(actual)) return null;
+      if (expected.allMatches(actual).isNotEmpty) return null;
       return Rejection(
           which: prefixFirst('does not match ', literal(expected)));
     });

pkgs/checks/test/extensions/string_test.dart

@@ -37,17 +37,29 @@ void main() {
     });
 
     group('matches', () {
-      test('succeeds for strings that match', () {
-        check('123').matches(RegExp(r'\d\d\d'));
+      test('succeeds for strings that match a regex', () {
+        check('123').matchesPattern(RegExp(r'\d\d\d'));
       });
-      test('fails for non-matching strings', () {
-        check('abc').isRejectedBy(it()..matches(RegExp(r'\d\d\d')),
+      test('succeeds for strings that match a string pattern', () {
+        check(r'\d').matchesPattern(r'\d');
+      });
+      test('fails for non-matching regex', () {
+        check('abc').isRejectedBy(it()..matchesPattern(RegExp(r'\d\d\d')),
             which: [r'does not match <RegExp: pattern=\d\d\d flags=>']);
       });
+      test('fails for non-matching string pattern', () {
+        // A string is _not_ converted to a regex, string patterns must match
+        // directly.
+        check('123').isRejectedBy(it()..matchesPattern(r'\d\d\d'),
+            which: [r"does not match '\\d\\d\\d'"]);
+      });
       test('can be described', () {
-        check(it<String>()..matches(RegExp(r'\d\d\d')))
+        check(it<String>()..matchesPattern(RegExp(r'\d\d\d')))
             .description
             .deepEquals([r'  matches <RegExp: pattern=\d\d\d flags=>']);
+        check(it<String>()..matchesPattern('abc'))
+            .description
+            .deepEquals([r"  matches 'abc'"]);
       });
     });