expectUnawaited abstract method

void expectUnawaited(
  1. Iterable<String> clause(),
  2. void predicate(
    1. T,
    2. void (
      1. Rejection
      )
    )
)

Expect that predicate will not invoke the passed callback with a Rejection at any point.

In contrast to expectAsync, a rejection is reported through a callback instead of through a returned Future. The callback may be invoked at any point that the failure surfaces.

This may be useful for a condition checking that some event never happens. If there is no specific point where it is know to be safe to stop listening for the event, there is no way to complete a returned future and consider the check "complete".

The clause callback returns a description of what is checked which stands on its own. For instance the is equal to <1> in:

Expected: a int that:
  is equal to <1>

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 expectUnawaited may not be performed by a condition callback passed to softCheck or softCheckAsync. The only useful effect of a late rejection is to throw a TestFailure when used with a check subject. Most conditions should prefer to use expect or expectAsync.

void someUnawaitableExpectation() async {
  await context.expectUnawaited(
      () => ['meets this unawaitable expectation'], (actual, reject) {
    final failureSignal = _completeIfFailed(actual);
    unawaited(failureSignal.then((_) {
      reject(Reject(
          which: ['unexpectedly failed this unawaited expectation']));
    }));
  });
}

Implementation

void expectUnawaited(Iterable<String> Function() clause,
    void Function(T, void Function(Rejection)) predicate);