Rename checkThat to check (#1880)

Save 4 characters of typing millions of types. The line will not read as
nicely in many situations, but it doesn't make a significant difference.

The shorter name, with no capital letters, also draws the least possible
attention to this name, which carries the least information of any part
of the expression.

Author: natebosch

pkgs/checks/CHANGELOG.md

@@ -1,5 +1,6 @@
-# 0.1.1-dev
+# 0.2.0
 
+-   **Breaking** `checkThat` renamed to `check`.
 -   Added an example.
 -   Include a stack trace in the failure description for unexpected errors from
     Futures or Streams.

pkgs/checks/README.md

@@ -1,22 +1,22 @@
 # Checking expectations with `checks`
 
-Expectations start with `checkThat`. This utility returns a `Subject`, and
+Expectations start with `check`. This utility returns a `Subject`, and
 expectations can be checked against the subject. Expectations are defined as
 extension methods, and different expectations will be available for subjects
 with different value types.
 
 ```dart
-checkThat(someValue).equals(expectedValue);
-checkThat(someList).deepEquals(expectedList);
-checkThat(someString).contains('expected pattern');
+check(someValue).equals(expectedValue);
+check(someList).deepEquals(expectedList);
+check(someString).contains('expected pattern');
 ```
 
 Multiple expectations can be checked against the same value using cascade
 syntax. When multiple expectations are checked against a single value, a failure
 will included descriptions of the expectations that already passed.
 
 ```dart
-checkThat(someString)
+check(someString)
   ..startsWith('a')
   ..endsWith('z')
   ..contains('lmno');
@@ -26,15 +26,15 @@ Some expectations return a `Subject` for another value derived from the original
 value - for instance reading a field or awaiting the result of a Future.
 
 ```dart
-checkThat(someString).length.equals(expectedLength);
-(await checkThat(someFuture).completes()).equals(expectedCompletion);
+check(someString).length.equals(expectedLength);
+(await check(someFuture).completes()).equals(expectedCompletion);
 ```
 
 Fields can be extracted from objects for checking further properties with the
 `has` utility.
 
 ```dart
-checkThat(someValue)
+check(someValue)
   .has((value) => value.property, 'property')
   .equals(expectedPropertyValue);
 ```
@@ -47,22 +47,22 @@ value as a subject will be recorded and replayed when it is applied as a
 condition. The `it()` utility returns a `ConditionSubject`.
 
 ```dart
-checkThat(someList).any(it()..isGreaterThan(0));
+check(someList).any(it()..isGreaterThan(0));
 ```
 
 Some complicated checks may be difficult to write with parenthesized awaited
 expressions, or impossible to write with cascade syntax. There are `which`
 utilities for both use cases which take a `Condition`.
 
 ```dart
-checkThat(someString)
+check(someString)
   ..startsWith('a')
   // A cascade would not be possible on `length`
   ..length.which(it()
     ..isGreatherThan(10)
     ..isLessThan(100));
 
-await checkThat(someFuture)
+await check(someFuture)
     .completes()
     .which(it()..equals(expectedCompletion));
 ```
@@ -126,7 +126,7 @@ extension CustomChecks on Subject<CustomType> {
 
 # Migrating from Matchers
 
-Replace calls to `expect` with a call to `checkThat` passing the first argument.
+Replace calls to `expect` with a call to `check` passing the first argument.
 When a direct replacement is available, change the second argument from calling
 a function returning a Matcher, to calling the extension method on the
 `Subject`.
@@ -137,9 +137,9 @@ correct replacement in `package:checks`.
 
 ```dart
 expect(actual, expected);
-checkThat(actual).equals(expected);
+check(actual).equals(expected);
 // or maybe
-checkThat(actual).deepEquals(expected);
+check(actual).deepEquals(expected);
 ```
 
 ## Differences in behavior from matcher

pkgs/checks/example/example.dart

@@ -8,14 +8,14 @@ import 'package:test/scaffolding.dart';
 void main() {
   test('sample test', () {
     final someValue = 5;
-    checkThat(someValue).equals(5);
+    check(someValue).equals(5);
 
     final someList = [1, 2, 3, 4, 5];
-    checkThat(someList).deepEquals([1, 2, 3, 4, 5]);
+    check(someList).deepEquals([1, 2, 3, 4, 5]);
 
     final someString = 'abcdefghijklmnopqrstuvwxyz';
 
-    checkThat(someString)
+    check(someString)
       ..startsWith('a')
       ..endsWith('z')
       ..contains('lmno');

pkgs/checks/lib/checks.dart

@@ -2,7 +2,7 @@
 // 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.
 
-export 'src/checks.dart' show checkThat, Subject, Skip, it;
+export 'src/checks.dart' show check, Subject, Skip, it;
 export 'src/extensions/async.dart'
     show ChainAsync, FutureChecks, StreamChecks, StreamQueueWrap;
 export 'src/extensions/core.dart'

pkgs/checks/lib/src/checks.dart

@@ -33,7 +33,7 @@ extension Skip<T> on Subject<T> {
   /// failure.
   ///
   /// ```dart
-  /// checkThat(actual)
+  /// check(actual)
   ///     ..stillChecked()
   ///     ..skip('reason the expectation is temporarily not met').notChecked();
   /// ```
@@ -57,11 +57,10 @@ extension Skip<T> on Subject<T> {
 /// messages.
 ///
 /// ```dart
-/// checkThat(actual).equals(expected);
+/// check(actual).equals(expected);
 /// ```
 @meta.useResult
-Subject<T> checkThat<T>(T value, {String? because}) =>
-    Subject._(_TestContext._root(
+Subject<T> check<T>(T value, {String? because}) => Subject._(_TestContext._root(
       value: _Present(value),
       // TODO - switch between "a" and "an"
       label: 'a $T',
@@ -239,7 +238,7 @@ abstract class Context<T> {
   ///
   /// May not be used from the context for a [Subject] created by [softCheck] or
   /// [softCheckAsync]. The only useful effect of a late rejection is to throw a
-  /// [TestFailure] when used with a [checkThat] subject. Most conditions should
+  /// [TestFailure] when used with a [check] subject. Most conditions should
   /// prefer to use [expect] or [expectAsync].
   void expectUnawaited(Iterable<String> Function() clause,
       void Function(T, void Function(Rejection)) predicate);
@@ -597,7 +596,7 @@ class CheckFailure {
 ///
 /// A subject may have some number of succeeding expectations, and the failure may
 /// be for an expectation against a property derived from the value at the root
-/// of the subject. For example, in `checkThat([]).length.equals(1)` the
+/// of the subject. For example, in `check([]).length.equals(1)` the
 /// specific value that gets rejected is `0` from the length of the list, and
 /// the subject that sees the rejection is nested with the label "has length".
 class FailureDetail {

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

@@ -205,7 +205,7 @@ extension StreamChecks<T> on Subject<StreamQueue<T>> {
   /// conditions.
   ///
   /// ```dart
-  /// await checkThat(StreamQueue(someStream)).inOrder([
+  /// await check(StreamQueue(someStream)).inOrder([
   ///   it()..emits().that(it()..equals(0)),
   ///   it()..emits().that(it()..equals(1)),
   //  ]);
@@ -445,9 +445,9 @@ extension ChainAsync<T> on Future<Subject<T>> {
   /// expression that would need parenthesis.
   ///
   /// ```dart
-  /// await checkThat(someFuture).completes().which(it()..equals('expected'));
+  /// await check(someFuture).completes().which(it()..equals('expected'));
   /// // or, with the intermediate `await`:
-  /// (await checkThat(someFuture).completes()).equals('expected');
+  /// (await check(someFuture).completes()).equals('expected');
   /// ```
   Future<void> which(Condition<T> condition) async {
     await condition.applyAsync(await this);

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

@@ -27,7 +27,7 @@ extension CoreChecks<T> on Subject<T> {
   /// in a way that would conflict.
   ///
   /// ```
-  /// checkThat(something)
+  /// check(something)
   ///   ..has((s) => s.foo, 'foo').equals(expectedFoo)
   ///   ..has((s) => s.bar, 'bar').which(it()
   ///     ..isLessThan(10)

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

@@ -47,7 +47,7 @@ extension IterableChecks<T> on Subject<Iterable<T>> {
   /// For example, the following will succeed:
   ///
   /// ```dart
-  /// checkThat([1, 0, 2, 0, 3]).containsInOrder([1, 2, 3]);
+  /// check([1, 0, 2, 0, 3]).containsInOrder([1, 2, 3]);
   /// ```
   ///
   /// Values in [elements] may be a `T`, a `Condition<T>`, or a
@@ -57,7 +57,7 @@ extension IterableChecks<T> on Subject<Iterable<T>> {
   /// equality operator.
   ///
   /// ```dart
-  /// checkThat([1, 0, 2, 0, 3])
+  /// check([1, 0, 2, 0, 3])
   ///   .containsInOrder([1, it<int>()..isGreaterThan(1), 3]);
   /// ```
   void containsInOrder(Iterable<Object?> elements) {

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

@@ -73,7 +73,7 @@ extension StringChecks on Subject<String> {
   ///
   /// For example, the following will succeed:
   ///
-  ///     checkThat('abcdefg').containsInOrder(['a','e']);
+  ///     check('abcdefg').containsInOrder(['a','e']);
   void containsInOrder(Iterable<String> expected) {
     context.expect(() => prefixFirst('contains, in order: ', literal(expected)),
         (actual) {
@@ -118,12 +118,12 @@ extension StringChecks on Subject<String> {
   ///
   /// For example the following will succeed:
   ///
-  ///     checkThat(' hello   world ').equalsIgnoringWhitespace('hello world');
+  ///     check(' hello   world ').equalsIgnoringWhitespace('hello world');
   ///
   /// While the following will fail:
   ///
-  ///     checkThat('helloworld').equalsIgnoringWhitespace('hello world');
-  ///     checkThat('he llo world').equalsIgnoringWhitespace('hello world');
+  ///     check('helloworld').equalsIgnoringWhitespace('hello world');
+  ///     check('he llo world').equalsIgnoringWhitespace('hello world');
   void equalsIgnoringWhitespace(String expected) {
     context.expect(
         () => prefixFirst('equals ignoring whitespace ', literal(expected)),

pkgs/checks/pubspec.yaml

@@ -1,5 +1,5 @@
 name: checks
-version: 0.1.1-dev
+version: 0.2.0
 description: >-
   A framework for checking values against expectations and building custom
   expectations.