Line data Source code
1 : // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file 2 : // for details. All rights reserved. Use of this source code is governed by a 3 : // BSD-style license that can be found in the LICENSE file. 4 : 5 : import 'dart:async'; 6 : 7 : import 'group.dart'; 8 : import 'message.dart'; 9 : import 'state.dart'; 10 : import 'suite.dart'; 11 : import 'test.dart'; 12 : 13 : /// A runnable instance of a test. 14 : /// 15 : /// This is distinct from [Test] in order to keep [Test] immutable. Running a 16 : /// test requires state, and [LiveTest] provides a view of the state of the test 17 : /// as it runs. 18 : /// 19 : /// If the state changes, [state] will be updated before [onStateChange] fires. 20 : /// Likewise, if an error is caught, it will be added to [errors] before being 21 : /// emitted via [onError]. If an error causes a state change, [onStateChange] 22 : /// will fire before [onError]. If an error or other state change causes the 23 : /// test to complete, [onComplete] will complete after [onStateChange] and 24 : /// [onError] fire. 25 : abstract class LiveTest { 26 : /// The suite within which this test is being run. 27 : Suite get suite; 28 : 29 : /// The groups within which this test is being run, from the outermost to the 30 : /// innermost. 31 : /// 32 : /// This will always contain at least the implicit top-level group. 33 : List<Group> get groups; 34 : 35 : /// The running test. 36 : Test get test; 37 : 38 : /// The current state of the running test. 39 : /// 40 : /// This starts as [Status.pending] and [Result.success]. It will be updated 41 : /// before [onStateChange] fires. 42 : /// 43 : /// Note that even if this is marked [Status.complete], the test may still be 44 : /// running code asynchronously. A test is considered complete either once it 45 : /// hits its first error or when all [expectAsync] callbacks have been called 46 : /// and any returned [Future] has completed, but it's possible for further 47 : /// processing to happen, which may cause further errors. It's even possible 48 : /// for a test that was marked [Status.complete] and [Result.success] to be 49 : /// marked as [Result.error] later. 50 : State get state; 51 : 52 : /// Returns whether this test has completed. 53 : /// 54 : /// This is equivalent to [state.status] being [Status.complete]. 55 : /// 56 : /// Note that even if this returns `true`, the test may still be 57 : /// running code asynchronously. A test is considered complete either once it 58 : /// hits its first error or when all [expectAsync] callbacks have been called 59 : /// and any returned [Future] has completed, but it's possible for further 60 : /// processing to happen, which may cause further errors. 61 44 : bool get isComplete => state.status == Status.complete; 62 : 63 : // A stream that emits a new [State] whenever [state] changes. 64 : // 65 : // This will only ever emit a [State] if it's different than the previous 66 : // [state]. It will emit an event after [state] has been updated. Note that 67 : // since this is an asynchronous stream, it's possible for [state] not to 68 : // match the [State] that it emits within the [Stream.listen] callback. 69 : Stream<State> get onStateChange; 70 : 71 : /// An unmodifiable list of all errors that have been caught while running 72 : /// this test. 73 : /// 74 : /// This will be updated before [onError] fires. These errors are not 75 : /// guaranteed to have the same types as when they were thrown; for example, 76 : /// they may need to be serialized across isolate boundaries. The stack traces 77 : /// will be [Chain]s. 78 : List<AsyncError> get errors; 79 : 80 : /// A stream that emits a new [AsyncError] whenever an error is caught. 81 : /// 82 : /// This will be emit an event after [errors] is updated. These errors are not 83 : /// guaranteed to have the same types as when they were thrown; for example, 84 : /// they may need to be serialized across isolate boundaries. The stack traces 85 : /// will be [Chain]s. 86 : Stream<AsyncError> get onError; 87 : 88 : /// A stream that emits messages produced by the test. 89 : Stream<Message> get onMessage; 90 : 91 : /// A [Future] that completes once the test is complete. 92 : /// 93 : /// This will complete after [onStateChange] has fired, and after [onError] 94 : /// has fired if the test completes because of an error. It's the same as the 95 : /// [Future] returned by [run]. 96 : /// 97 : /// Note that even once this completes, the test may still be running code 98 : /// asynchronously. A test is considered complete either once it hits its 99 : /// first error or when all [expectAsync] callbacks have been called and any 100 : /// returned [Future] has completed, but it's possible for further processing 101 : /// to happen, which may cause further errors. 102 : Future get onComplete; 103 : 104 : /// The name of this live test without any group prefixes. 105 0 : String get individualName { 106 0 : var group = groups.last; 107 0 : if (group.name.isEmpty) return test.name; 108 0 : if (!test.name.startsWith(group.name)) return test.name; 109 : 110 : // The test will have the same name as the group for virtual tests created 111 : // to represent skipping the entire group. 112 0 : if (test.name.length == group.name.length) return ''; 113 : 114 0 : return test.name.substring(group.name.length + 1); 115 : } 116 : 117 : /// Loads a copy of this [LiveTest] that's able to be run again. 118 0 : LiveTest copy() => test.load(suite, groups: groups); 119 : 120 : /// Signals that this test should start running as soon as possible. 121 : /// 122 : /// A test may not start running immediately for various reasons specific to 123 : /// the means by which it's defined. Until it starts running, [state] will 124 : /// continue to be marked [Status.pending]. 125 : /// 126 : /// This returns the same [Future] as [onComplete]. It may not be called more 127 : /// than once. 128 : Future run(); 129 : 130 : /// Signals that this test should stop emitting events and release any 131 : /// resources it may have allocated. 132 : /// 133 : /// Once [close] is called, [onComplete] will complete if it hasn't already 134 : /// and [onStateChange] and [onError] will close immediately. This means that, 135 : /// if the test was running at the time [close] is called, it will never emit 136 : /// a [Status.complete] state-change event. Once a test is closed, [expect] 137 : /// and [expectAsync] will throw a [ClosedException] to help the test 138 : /// terminate as quickly as possible. 139 : /// 140 : /// This doesn't automatically happen after the test completes because there 141 : /// may be more asynchronous work going on in the background that could 142 : /// produce new errors. 143 : /// 144 : /// Returns a [Future] that completes once all resources are released *and* 145 : /// the test has completed. This allows the caller to wait until the test's 146 : /// tear-down logic has run. 147 : Future close(); 148 : }