Take Condition for async nesting expectations (#1896)

Avoid the awkwardness of awaiting before chaining conditions, or needing
a `which` utility to chain on a Future.

This introduces a discrepancy between chaining for sync vs async
expectations, but it makes many common async expectations nicer to read.

- Remove `which` and a reference to it in README.
- Update `nestAsync` to take `nestedCondition` argument instead of
  returning a `Subject`. This forces all async conditions to follow the
  same pattern.
- Update `nestAsync` doc example to use the new signature.
- Mention how to check subsequent conditions in the doc for `nest`, and
  in the doc for `nestAsync` explicitly contrast with `nest`.
- Remove now unnecessary nesting handling from `_ReplayContext`.
- Update all async expectations using `nestAsync` to use the new
  signature and describe usage in their docs.
- Add `_LazyCondition` in `test_shared.dart`. This could prove useful
  enough to put directly in `Condition` at some point. This allows the
  condition that runs to be based on the `actual` value from the
  predicate, which is an unusual situation for testing within the
  library since it mirrors the defaulting that happens in
  `_TestContext`.

Author: natebosch

pkgs/checks/CHANGELOG.md

@@ -4,6 +4,15 @@
     -   `checkThat` renamed to `check`.
     -   `nest` and `nestAsync` take `Iterable<String> Function()` arguments for
         `label` instead of `String`.
+    -   Async expectation extensions `completes`, `throws`, `emits`, and
+        `emitsError` no longer return a `Future<Subject>`. Instead they take an
+        optional `Condition` argument which can check expectations that would
+        have been checked on the returned subject.
+    -   `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.
 -   Added an example.
 -   Include a stack trace in the failure description for unexpected errors from
     Futures or Streams.

pkgs/checks/README.md

@@ -50,9 +50,8 @@ condition. The `it()` utility returns a `ConditionSubject`.
 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`.
+Some complicated checks may be not be possible to write with cascade syntax.
+There is a `which` utility for this use case which takes a `Condition`.
 
 ```dart
 check(someString)
@@ -61,10 +60,6 @@ check(someString)
   ..length.which(it()
     ..isGreatherThan(10)
     ..isLessThan(100));
-
-await check(someFuture)
-    .completes()
-    .which(it()..equals(expectedCompletion));
 ```
 
 # Writing custom expectations

pkgs/checks/lib/checks.dart

@@ -4,7 +4,7 @@
 
 export 'src/checks.dart' show SkipExtension, Subject, check, it;
 export 'src/extensions/async.dart'
-    show ChainAsync, FutureChecks, StreamChecks, WithQueueExtension;
+    show FutureChecks, StreamChecks, WithQueueExtension;
 export 'src/extensions/core.dart' show BoolChecks, CoreChecks, NullableChecks;
 export 'src/extensions/function.dart' show FunctionChecks;
 export 'src/extensions/iterable.dart' show IterableChecks;

pkgs/checks/lib/src/checks.dart

@@ -178,8 +178,17 @@ Future<Iterable<String>> describeAsync<T>(Condition<T> condition) async {
 
 /// A set of expectations that are checked against the value when applied to a
 /// [Subject].
+///
+/// This class should not be implemented or extended.
 abstract class Condition<T> {
+  /// Check the expectations of this condition against [subject].
+  ///
+  /// The [subject] should throw if any asynchronous expectations are checked.
+  /// It is not possible to wait for for asynchronous expectations to be fully
+  /// applied with this method.
   void apply(Subject<T> subject);
+
+  /// Check the expectations of this condition against [subject].
   Future<void> applyAsync(Subject<T> subject);
 }
 
@@ -481,6 +490,9 @@ abstract class Context<T> {
   /// [Extracted.rejection] describing the problem. Otherwise it should return
   /// an [Extracted.value].
   ///
+  /// Subsequent expectations can be checked for the extracted value on the
+  /// returned [Subject].
+  ///
   /// {@macro label_description}
   ///
   /// If [atSameLevel] is true then the returned [Extracted.value] should hold
@@ -518,6 +530,10 @@ abstract class Context<T> {
   /// [Extracted.rejection] describing the problem. Otherwise it should return
   /// an [Extracted.value].
   ///
+  /// In contrast to [nest], subsequent expectations need to be passed in
+  /// [nestedCondition] which will be applied to the subject for the extracted
+  /// value.
+  ///
   /// {@macro label_description}
   ///
   /// {@macro description_lines}
@@ -527,17 +543,19 @@ abstract class Context<T> {
   /// {@macro async_limitations}
   ///
   /// ```dart
-  /// Future<Subject<Foo>> get someAsyncValue async => await context
-  ///         .nestAsync(() => ['has someAsyncValue'], (actual) async {
-  ///       if (await _cannotReadAsyncValue(actual)) {
-  ///         return Extracted.rejection(
-  ///             which: ['cannot read someAsyncValue']);
-  ///       }
-  ///       return Extracted.value(await _readAsyncValue(actual));
-  ///     });
+  /// Future<void> someAsyncResult([Condition<Result> resultCondition]) async {
+  ///   await context.nestAsync(() => ['has someAsyncResult'], (actual) async {
+  ///     if (await _asyncOperationFailed(actual)) {
+  ///       return Extracted.rejection(which: ['cannot read someAsyncResult']);
+  ///     }
+  ///     return Extracted.value(await _readAsyncResult(actual));
+  ///   }, resultCondition);
+  /// }
   /// ```
-  Future<Subject<R>> nestAsync<R>(Iterable<String> Function() label,
-      FutureOr<Extracted<R>> Function(T) extract);
+  Future<void> nestAsync<R>(
+      Iterable<String> Function() label,
+      FutureOr<Extracted<R>> Function(T) extract,
+      Condition<R>? nestedCondition);
 }
 
 /// A property extracted from a value being checked, or a rejection.
@@ -752,8 +770,10 @@ class _TestContext<T> implements Context<T>, _ClauseDescription {
   }
 
   @override
-  Future<Subject<R>> nestAsync<R>(Iterable<String> Function() label,
-      FutureOr<Extracted<R>> Function(T) extract) async {
+  Future<void> nestAsync<R>(
+      Iterable<String> Function() label,
+      FutureOr<Extracted<R>> Function(T) extract,
+      Condition<R>? nestedCondition) async {
     if (!_allowAsync) {
       throw StateError(
           'Async expectations cannot be used on a synchronous subject');
@@ -770,7 +790,7 @@ class _TestContext<T> implements Context<T>, _ClauseDescription {
     final value = result._value ?? _Absent<R>();
     final context = _TestContext<R>._child(value, label, this);
     _clauses.add(context);
-    return Subject._(context);
+    await nestedCondition?.applyAsync(Subject<R>._(context));
   }
 
   CheckFailure _failure(Rejection rejection) =>
@@ -843,9 +863,11 @@ class _SkippedContext<T> implements Context<T> {
   }
 
   @override
-  Future<Subject<R>> nestAsync<R>(Iterable<String> Function() label,
-      FutureOr<Extracted<R>> Function(T p1) extract) async {
-    return Subject._(_SkippedContext());
+  Future<void> nestAsync<R>(
+      Iterable<String> Function() label,
+      FutureOr<Extracted<R>> Function(T p1) extract,
+      Condition<R>? nestedCondition) async {
+    // no-op
   }
 }
 
@@ -1066,13 +1088,12 @@ class _ReplayContext<T> implements Context<T>, Condition<T> {
   }
 
   @override
-  Future<Subject<R>> nestAsync<R>(Iterable<String> Function() label,
-      FutureOr<Extracted<R>> Function(T) extract) async {
-    final nestedContext = _ReplayContext<R>();
+  Future<void> nestAsync<R>(
+      Iterable<String> Function() label,
+      FutureOr<Extracted<R>> Function(T) extract,
+      Condition<R>? nestedCondition) async {
     _interactions.add((c) async {
-      var result = await c.nestAsync(label, extract);
-      await nestedContext.applyAsync(result);
+      await c.nestAsync(label, extract, nestedCondition);
     });
-    return Subject._(nestedContext);
   }
 }