nestAsync<R> abstract method

Future<void> nestAsync<R>(Iterable<String> label(), FutureOr<Extracted<R>> extract(T), AsyncCondition<R>? nestedCondition)

Extract an asynchronous property from the value for further checking.

If the property cannot be extracted, extract should return an 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.

The label callback returns a description of the extracted subject as it relates to the original subject. For instance the completes to a value in:

Expected a Future<int> that:
  completes to a value that:
    is equal to <1>

A label should also be sensible when it is read as a clause. If no further expectations are checked on the extracted subject, or if the extraction is rejected, the "that:" is omitted in the output.

  Expected a Future<int> that:
    completes to a value

Description callbacks return an Iterable<String> where each element is a line in the output. Individual elements should not contain newlines. Utilities such as prefixFirst, postfixLast, and literal may be useful to format values which are potentially multiline.

The description of an expectation may never be shown to the user, so the callback may never be invoked. If all the conditions on a subject succeed, or if the failure detail for a failed softCheck is never read, the descriptions will be unused. String formatting for the descriptions should be performed in the callback, not ahead of time.

The context for a subject may hold a real "actual" value to test against, or it may have a placeholder within a call to describe. A context with a placeholder value will not invoke the callback to check expectations.

If both callbacks are invoked, the description callback will always be called strictly after the expectation callback is called.

Callbacks passed to a context should not throw.

Calls to expectAsync or nestAsync must not be performed by a condition callback passed to softCheck or describe. Use softCheckAsync or describeAsync for any condition which checks async expectations.

Future<void> someAsyncResult(
    [AsyncCondition<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);
}

Implementation

Future<void> nestAsync<R>(
    Iterable<String> Function() label,
    FutureOr<Extracted<R>> Function(T) extract,
    AsyncCondition<R>? nestedCondition);