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 15 : 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 : String get individualName {
106 0 : var group = groups.last;
107 0 : if (group.name == null) 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 : }
|