| // Copyright (c) 2022, the Dart project authors. Please see the AUTHORS file | |
| // 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. | |
| import 'dart:async'; | |
| import 'dart:convert'; | |
| import 'package:async/async.dart'; | |
| import 'package:meta/meta.dart' show awaitNotRequired; | |
| import '../../context.dart'; | |
| extension FutureChecks<T> on Subject<Future<T>> { | |
| /// Expects that the `Future` completes to a value without throwing. | |
| /// | |
| /// Fails if the future completes as an error. | |
| /// | |
| /// Pass [completionCondition] to check expectations on the completion result. | |
| /// | |
| /// The returned future will complete when the subject future has completed, | |
| /// and [completionCondition] has optionally been checked. | |
| /// | |
| /// {@example /example/async/future/completes.dart} | |
| @awaitNotRequired | |
| Future<Subject<T>> completes([Condition<T>? completionCondition]) { | |
| return context.nestAsync<T>( | |
| () => ['completes to a value'], | |
| addPredicate: (predicateNoun) => 'completes to $predicateNoun', | |
| (actual) async { | |
| try { | |
| return Extracted.value(await actual); | |
| } catch (e, st) { | |
| return Extracted.rejection( | |
| actual: ['a future that completes as an error'], | |
| which: [ | |
| ...prefixFirst('threw ', postfixLast(' at:', literal(e))), | |
| ...indent(LineSplitter.split(st.toString())), | |
| ], | |
| ); | |
| } | |
| }, | |
| completionCondition, | |
| ); | |
| } | |
| /// Expects that the `Future` never completes as a value or an error. | |
| /// | |
| /// Immediately returns and does not cause the test to remain running if it | |
| /// ends. | |
| /// If the future completes at any time, raises a test failure. This may | |
| /// happen after the test has already appeared to succeed. | |
| /// | |
| /// Not compatible with [Condition.softCheck] or [Condition.softCheckSync] | |
| /// since there is no concrete end point where this condition has definitely | |
| /// succeeded. | |
| /// | |
| /// {@example /example/async/future/does_not_complete.dart} | |
| void get doesNotComplete { | |
| context.expectUnawaited(() => ['does not complete'], (actual, reject) { | |
| unawaited( | |
| actual.then( | |
| (r) { | |
| reject( | |
| Rejection( | |
| actual: prefixFirst('a future that completed to ', literal(r)), | |
| ), | |
| ); | |
| }, | |
| onError: (Object e, StackTrace st) { | |
| reject( | |
| Rejection( | |
| actual: ['a future that completed as an error'], | |
| which: [ | |
| ...prefixFirst('threw ', postfixLast(' at:', literal(e))), | |
| ...indent(LineSplitter.split(st.toString())), | |
| ], | |
| ), | |
| ); | |
| }, | |
| ), | |
| ); | |
| }); | |
| } | |
| /// Expects that the `Future` completes as an error. | |
| /// | |
| /// Fails if the future completes to a value. | |
| /// | |
| /// Pass [errorCondition] to check expectations on the error thrown by the | |
| /// future. | |
| /// | |
| /// The returned future will complete when the subject future has completed, | |
| /// and [errorCondition] has optionally been checked. | |
| /// | |
| /// {@example /example/async/future/throws.dart} | |
| @awaitNotRequired | |
| Future<Subject<E>> throws<E extends Object>([Condition<E>? errorCondition]) { | |
| return context.nestAsync<E>( | |
| () => ['completes to an error${E == Object ? '' : ' of type $E'}'], | |
| addPredicate: (predicateNoun) => 'throws $predicateNoun', | |
| (actual) async { | |
| try { | |
| return Extracted.rejection( | |
| actual: prefixFirst('completed to ', literal(await actual)), | |
| which: ['did not throw'], | |
| ); | |
| } on E catch (e) { | |
| return Extracted.value(e); | |
| } catch (e, st) { | |
| return Extracted.rejection( | |
| actual: prefixFirst('completed to error ', literal(e)), | |
| which: [ | |
| 'threw an exception that is not a $E at:', | |
| ...indent(LineSplitter.split(st.toString())), | |
| ], | |
| ); | |
| } | |
| }, | |
| errorCondition, | |
| ); | |
| } | |
| } | |
| /// Expectations on a [StreamQueue]. | |
| /// | |
| /// Streams should be wrapped in user test code so that any reuse of the same | |
| /// Stream, and the full stream lifecycle, is explicit. | |
| extension StreamChecks<T> on Subject<StreamQueue<T>> { | |
| /// Calls [Context.expectAsync] and wraps [predicate] with a transaction. | |
| /// | |
| /// The transaction is committed if the check passes, or rejected if it fails. | |
| @awaitNotRequired | |
| Future<void> _expectAsync( | |
| Iterable<String> Function() clause, | |
| FutureOr<Rejection?> Function(StreamQueue<T>) predicate, | |
| ) => context.expectAsync(clause, (actual) async { | |
| final transaction = actual.startTransaction(); | |
| final copy = transaction.newQueue(); | |
| final result = await predicate(copy); | |
| if (result == null) { | |
| transaction.commit(copy); | |
| } else { | |
| transaction.reject(); | |
| } | |
| return result; | |
| }); | |
| /// Expect that the `Stream` emits a value without first emitting an error. | |
| /// | |
| /// Fails if the stream emits an error instead of a value, or closes without | |
| /// emitting a value. | |
| /// | |
| /// If an error is emitted the queue will be left in its original state, the | |
| /// error will not be consumed. | |
| /// If an event is emitted, it will be consumed from the queue. | |
| /// | |
| /// Pass [emittedCondition] to check expectations on the value emitted by the | |
| /// stream. | |
| /// | |
| /// The returned future will complete when the stream has emitted, errored, or | |
| /// ended, and the [emittedCondition] has optionally been checked. | |
| /// | |
| /// {@example /example/async/stream_queue/emits.dart} | |
| @awaitNotRequired | |
| Future<Subject<T>> emits([Condition<T>? emittedCondition]) { | |
| return context.nestAsync<T>( | |
| () => ['emits a value'], | |
| addPredicate: (predicateNoun) => 'emits $predicateNoun', | |
| (actual) async { | |
| if (!await actual.hasNext) { | |
| return Extracted.rejection( | |
| actual: ['a stream that closed'], | |
| which: ['did not emit a value'], | |
| ); | |
| } | |
| try { | |
| await actual.peek; | |
| return Extracted.value(await actual.next); | |
| } catch (e, st) { | |
| return Extracted.rejection( | |
| actual: prefixFirst('a stream that emitted error ', literal(e)), | |
| which: [ | |
| 'emitted an error instead of a value at:', | |
| ...indent(LineSplitter.split(st.toString())), | |
| ], | |
| ); | |
| } | |
| }, | |
| emittedCondition, | |
| ); | |
| } | |
| /// Expects that the stream emits an error of type [E]. | |
| /// | |
| /// Fails if the stream emits any value. | |
| /// Fails if the stream emits an error with an incorrect type. | |
| /// Fails if the stream closes without emitting an error. | |
| /// | |
| /// If an event is emitted the queue will be left in its original state, the | |
| /// event will not be consumed. | |
| /// If an error is emitted, it will be consumed from the queue. | |
| /// | |
| /// Pass [errorCondition] to check expectations on the error emitted by the | |
| /// stream. | |
| /// | |
| /// The returned future will complete when the stream has emitted, errored, or | |
| /// ended, and the [errorCondition] has optionally been checked. | |
| /// | |
| /// {@example /example/async/stream_queue/emits_error.dart} | |
| @awaitNotRequired | |
| Future<Subject<E>> emitsError<E extends Object>([ | |
| Condition<E>? errorCondition, | |
| ]) { | |
| return context.nestAsync<E>( | |
| () => ['emits an error${E == Object ? '' : ' of type $E'}'], | |
| addPredicate: (predicateNoun) => 'emits error $predicateNoun', | |
| (actual) async { | |
| if (!await actual.hasNext) { | |
| return Extracted.rejection( | |
| actual: ['a stream that closed'], | |
| which: ['did not emit an error'], | |
| ); | |
| } | |
| try { | |
| final value = await actual.peek; | |
| return Extracted.rejection( | |
| actual: prefixFirst('a stream that emitted ', literal(value)), | |
| which: ['emitted a value instead of an error'], | |
| ); | |
| } on E catch (e) { | |
| await actual.next.then<void>((_) {}, onError: (_) {}); | |
| return Extracted.value(e); | |
| } catch (e, st) { | |
| return Extracted.rejection( | |
| actual: prefixFirst('a stream that emitted error ', literal(e)), | |
| which: [ | |
| 'emitted an error which is not $E at:', | |
| ...indent(LineSplitter.split(st.toString())), | |
| ], | |
| ); | |
| } | |
| }, | |
| errorCondition, | |
| ); | |
| } | |
| /// Expects that the `Stream` emits any number of events before emitting an | |
| /// event that satisfies [condition]. | |
| /// | |
| /// Returns a `Future` that completes after the stream has emitted an event | |
| /// that satisfies [condition]. | |
| /// | |
| /// Fails if the stream emits an error or closes before emitting a matching | |
| /// event. | |
| /// | |
| /// If this expectation fails, the source queue will be left in its original | |
| /// state. | |
| /// If this expectation succeeds, consumes the matching event and all prior | |
| /// events. | |
| /// | |
| /// {@example /example/async/stream_queue/emits_through.dart} | |
| @awaitNotRequired | |
| Future<void> emitsThrough(Condition<T> condition) async { | |
| await _expectAsync( | |
| () { | |
| final description = condition.describe(); | |
| if (description is Iterable<String>) { | |
| return ['emits any values then emits a value that:', ...description]; | |
| } | |
| return [ | |
| 'emits any values then emits a value satisfying an asynchronous condition', | |
| ]; | |
| }, | |
| (actual) async { | |
| final emitted = _EmittedValues<T>(); | |
| while (await actual.hasNext) { | |
| final value = await actual.next; | |
| if (await condition.softCheck(value) == null) { | |
| return null; | |
| } | |
| emitted.add(value); | |
| } | |
| return Rejection( | |
| actual: emitted.count == 0 | |
| ? ['a stream that closed'] | |
| : prefixFirst( | |
| 'a stream that closed after emitting ', | |
| emitted.describe(), | |
| ), | |
| which: ['did not emit a matching value'], | |
| ); | |
| }, | |
| ); | |
| } | |
| /// Expects that the stream satisfies each condition in [conditions] serially. | |
| /// | |
| /// Waits for each condition to be satisfied or rejected before checking the | |
| /// next. Subsequent conditions will not see any events consumed by earlier | |
| /// conditions. | |
| /// | |
| /// If this expectation fails, the source queue will be left in its original | |
| /// state. | |
| /// If this expectation succeeds, consumes as many events from the source | |
| /// stream as are consumed by all the conditions. | |
| /// | |
| /// {@example /example/async/stream_queue/in_order.dart} | |
| @awaitNotRequired | |
| Future<void> inOrder(Iterable<Condition<StreamQueue<T>>> conditions) async { | |
| conditions = conditions.toList(); | |
| final descriptions = <String>[]; | |
| await _expectAsync( | |
| () => descriptions.isEmpty | |
| ? ['satisfies ${conditions.length} conditions in order'] | |
| : descriptions, | |
| (actual) async { | |
| var satisfiedCount = 0; | |
| for (var condition in conditions) { | |
| descriptions.addAll(await condition.describe()); | |
| final failure = await condition.softCheck(actual); | |
| if (failure != null) { | |
| return Rejection( | |
| actual: ['a stream'], | |
| which: [ | |
| if (satisfiedCount > 0) | |
| 'satisfied $satisfiedCount conditions then', | |
| 'failed to satisfy the condition at index $satisfiedCount', | |
| 'because it:', | |
| ...indent(failure.describeNested()), | |
| ], | |
| ); | |
| } | |
| satisfiedCount++; | |
| } | |
| return null; | |
| }, | |
| ); | |
| } | |
| /// Expects that the stream statisfies at least one condition from | |
| /// [conditions]. | |
| /// | |
| /// If this expectation fails, the source queue will be left in its original | |
| /// state. | |
| /// If this expectation succeeds, consumes the same events from the source | |
| /// queue as the satisfied condition. If multiple conditions are satisfied, | |
| /// chooses the condition which consumed the most events. | |
| /// | |
| /// {@example /example/async/stream_queue/any_of.dart} | |
| @awaitNotRequired | |
| Future<void> anyOf(Iterable<Condition<StreamQueue<T>>> conditions) { | |
| conditions = conditions.toList(); | |
| if (conditions.isEmpty) throw ArgumentError('conditions may not be empty'); | |
| final descriptions = <Iterable<String>>[]; | |
| return context.expectAsync( | |
| () => descriptions.isEmpty | |
| ? ['satisfies any of ${conditions.length} conditions'] | |
| : [ | |
| 'satisfies one of:', | |
| for (var i = 0; i < descriptions.length; i++) ...[ | |
| ...descriptions[i], | |
| if (i < descriptions.length - 1) 'or,', | |
| ], | |
| ], | |
| (actual) async { | |
| final transaction = actual.startTransaction(); | |
| StreamQueue<T>? longestAccepted; | |
| final descriptionFuture = conditions | |
| .map((c) async => await c.describe()) | |
| .wait; | |
| // soft checks are unexpected to throw, if they do the unhandled async | |
| // error should surface in the test runner. | |
| final failures = await conditions.map((condition) async { | |
| final copy = transaction.newQueue(); | |
| final failure = await condition.softCheck(copy); | |
| if (failure == null && | |
| (longestAccepted == null || | |
| copy.eventsDispatched > longestAccepted!.eventsDispatched)) { | |
| longestAccepted = copy; | |
| } | |
| return failure; | |
| }).wait; | |
| descriptions.addAll(await descriptionFuture); | |
| if (longestAccepted case final accepted?) { | |
| transaction.commit(accepted); | |
| return null; | |
| } | |
| transaction.reject(); | |
| return Rejection( | |
| actual: ['a stream'], | |
| which: [ | |
| 'failed to satisfy any condition', | |
| for (var i = 0; i < failures.length; i++) ...[ | |
| 'failed the condition at index $i because it:', | |
| ...indent(failures[i]!.describeNested()), | |
| ], | |
| ], | |
| ); | |
| }, | |
| ); | |
| } | |
| /// Expects that the stream closes without emitting any event that satisfies | |
| /// [condition]. | |
| /// | |
| /// Returns a `Future` that completes after the stream has closed. | |
| /// | |
| /// Fails if the stream emits any even that satisfies [condition]. | |
| /// | |
| /// If this expectation fails, the source queue will be left in its original | |
| /// state. | |
| /// If this expectation succeeds, consumes all the events that did not satisfy | |
| /// [condition] until the end of the stream. | |
| /// | |
| /// {@example /example/async/stream_queue/never_emits.dart} | |
| @awaitNotRequired | |
| Future<void> neverEmits(Condition<T> condition) async { | |
| await _expectAsync( | |
| () { | |
| final description = condition.describe(); | |
| if (description is Iterable<String>) { | |
| return ['never emits a value that:', ...description]; | |
| } | |
| return ['never emits a value satisfying an asynchronous condition']; | |
| }, | |
| (actual) async { | |
| final emitted = _EmittedValues<T>(); | |
| await for (var value in actual.rest) { | |
| emitted.add(value); | |
| if (await condition.softCheck(value) == null) { | |
| return Rejection( | |
| actual: prefixFirst('a stream that emitted ', emitted.describe()), | |
| which: prefixFirst( | |
| 'emitted a matching value at index ${emitted.count - 1}: ', | |
| literal(value), | |
| ), | |
| ); | |
| } | |
| } | |
| return null; | |
| }, | |
| ); | |
| } | |
| /// Optionally consumes an event that matches [condition] from the stream. | |
| /// | |
| /// This expectation never fails. | |
| /// | |
| /// If a non-matching event is emitted, no events are consumed. | |
| /// If a matching event is emitted, that event is consumed. | |
| /// | |
| /// {@example /example/async/stream_queue/may_emit.dart} | |
| @awaitNotRequired | |
| Future<void> mayEmit(Condition<T> condition) { | |
| return context.expectAsync( | |
| () { | |
| final description = condition.describe(); | |
| if (description is Iterable<String>) { | |
| return ['may emit a value that:', ...description]; | |
| } | |
| return ['may emit a value satisfying an asynchronous condition']; | |
| }, | |
| (actual) async { | |
| if (!await actual.hasNext) return null; | |
| try { | |
| final value = await actual.peek; | |
| if (await condition.softCheck(value) == null) { | |
| await actual.next; | |
| } | |
| } catch (_) { | |
| // Ignore an emitted error - it does not match he event. | |
| } | |
| return null; | |
| }, | |
| ); | |
| } | |
| /// Optionally consumes events that match [condition] from the stream. | |
| /// | |
| /// This expectation never fails. | |
| /// | |
| /// Consumes matching events until one of the following happens: | |
| /// - A non-matching event is emitted. | |
| /// - An error is emitted. | |
| /// - The stream closes. | |
| /// | |
| /// {@example /example/async/stream_queue/may_emit_multiple.dart} | |
| @awaitNotRequired | |
| Future<void> mayEmitMultiple(Condition<T> condition) { | |
| return context.expectAsync( | |
| () { | |
| final description = condition.describe(); | |
| if (description is Iterable<String>) { | |
| return ['may emit a value that:', ...description]; | |
| } | |
| return ['may emit a value satisfying an asynchronous condition']; | |
| }, | |
| (actual) async { | |
| while (await actual.hasNext) { | |
| try { | |
| final value = await actual.peek; | |
| if (await condition.softCheck(value) == null) { | |
| await actual.next; | |
| } else { | |
| return null; | |
| } | |
| } catch (_) { | |
| return null; | |
| } | |
| } | |
| return null; | |
| }, | |
| ); | |
| } | |
| /// Expects that the stream closes without emitting any events or errors. | |
| /// | |
| /// If this expectation fails, the source queue will be left in its original | |
| /// state, the event or error that caused it to fail will not be consumed. | |
| /// | |
| /// {@example /example/async/stream_queue/is_done.dart} | |
| @awaitNotRequired | |
| Future<void> get isDone async { | |
| await _expectAsync(() => ['is done'], (actual) async { | |
| if (!await actual.hasNext) return null; | |
| try { | |
| final value = await actual.next; | |
| return Rejection( | |
| actual: prefixFirst('a stream that emitted ', literal(value)), | |
| which: ['emitted a value before closing'], | |
| ); | |
| } catch (e, st) { | |
| return Rejection( | |
| actual: prefixFirst('a stream that emitted error ', literal(e)), | |
| which: [ | |
| 'emitted an error before closing at:', | |
| ...indent(LineSplitter.split(st.toString())), | |
| ], | |
| ); | |
| } | |
| }); | |
| } | |
| } | |
| /// The values emitted by a stream while checking an expectation, for | |
| /// describing the stream in a rejection. | |
| /// | |
| /// Keeps only the first [_limit] values, along with the [count] of all values, | |
| /// so that checking a long stream does not hold on to every value. | |
| class _EmittedValues<T> { | |
| static const _limit = 25; | |
| final _values = <T>[]; | |
| /// The number of values emitted, including those which were not kept. | |
| int count = 0; | |
| void add(T value) { | |
| if (_values.length < _limit) _values.add(value); | |
| count++; | |
| } | |
| /// A description of the emitted values. | |
| /// | |
| /// Lists the values, for example `[1, 2, 3]`, or when there are more values | |
| /// than were kept, `30 values, starting with [1, 2, 3, ...]`. | |
| Iterable<String> describe() => count <= _limit | |
| ? literal(_values) | |
| : prefixFirst('$count values, starting with ', literal(_values)); | |
| } | |
| extension WithQueueExtension<T> on Subject<Stream<T>> { | |
| /// Wrap the stream in a [StreamQueue] to allow using checks from | |
| /// [StreamChecks]. | |
| /// | |
| /// Stream expectations operate on a queue, instead of directly on the stream, | |
| /// so that they can support conditional expectations and check multiple | |
| /// possibilities from the same point in the stream. | |
| /// | |
| /// {@example /example/async/stream/with_queue.dart} | |
| Subject<StreamQueue<T>> get withQueue => context.nest( | |
| () => [], | |
| (actual) => Extracted.value(StreamQueue(actual)), | |
| atSameLevel: true, | |
| ); | |
| } | |
| extension FutureSubjectExtension<T> on Future<Subject<T>> { | |
| /// Applies the expectations invoked in [condition] to this subject. | |
| /// | |
| /// Use this method when it would otherwise not be possible to check multiple | |
| /// expectations for this subject due to cascade notation already being used | |
| /// in a way that would conflict. | |
| /// | |
| /// ```dart | |
| /// await check(someFuture).completes().which(.it() | |
| /// ..isLessThan(10) | |
| /// ..isGreaterThan(0)); | |
| /// ``` | |
| /// | |
| /// {@example /example/async/future_subject/which.dart} | |
| @awaitNotRequired | |
| Future<void> which(Condition<T> condition) async { | |
| await condition.apply(await this); | |
| } | |
| } |