-
Notifications
You must be signed in to change notification settings - Fork 99
/
ReceiveTurbine.kt
129 lines (116 loc) · 4.64 KB
/
ReceiveTurbine.kt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
/*
* Copyright (C) 2022 Square, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package app.cash.turbine
import kotlinx.coroutines.channels.ReceiveChannel
public interface ReceiveTurbine<T> {
/**
* Returns the underlying [ReceiveChannel].
*/
public fun asChannel(): ReceiveChannel<T>
/**
* Cancel this [ReceiveTurbine].
*
* If it is backed by an underlying coroutine (e.g. the coroutine run
* by [test]), that coroutine will also be cancelled.
*
* If [cancel] is invoked before the underlying coroutine or channel has been closed, [ensureAllEventsConsumed]
* will succeed even if the terminal event is not consumed.
*/
public suspend fun cancel()
/**
* Cancel this [ReceiveTurbine] and ignore any events which have already been received.
*
* If it is backed by an underlying coroutine (e.g. the coroutine run
* by [test]), that coroutine will also be cancelled. If called within a [test] block, the [test] block
* will exit.
*/
public suspend fun cancelAndIgnoreRemainingEvents()
/**
* Cancel this [ReceiveTurbine] and return any events which have already been received.
*
* If it is backed by an underlying coroutine (e.g. the coroutine run
* by [test]), that coroutine will also be cancelled. If called within a [test] block, the [test] block
* will exit.
*/
public suspend fun cancelAndConsumeRemainingEvents(): List<Event<T>>
/**
* Assert that there are no unconsumed events which have already been received.
*
* @throws AssertionError if unconsumed events are found.
*/
public fun expectNoEvents()
/**
* Returns the most recent item that has already been received.
* If a complete event has been received with no item being received
* previously, this function will throw an [AssertionError]. If an error event
* has been received, this function will throw the underlying exception.
*
* @throws AssertionError if no item was emitted.
*/
public fun expectMostRecentItem(): T
/**
* Assert that an event was received and return it.
* This function will suspend if no events have been received.
*
* When this [ReceiveTurbine] is in a terminal state ([Event.Complete] or [Event.Error]), this method
* will yield the same result every time it is called.
*/
public suspend fun awaitEvent(): Event<T>
/**
* Assert that the next event received was an item and return it.
* This function will suspend if no events have been received.
*
* When this [ReceiveTurbine] is in a terminal state ([Event.Complete] or [Event.Error]), this method
* will yield the same result every time it is called.
*
* @throws AssertionError if the next event was completion or an error.
*/
public suspend fun awaitItem(): T
/**
* Assert that [count] item events were received and ignore them.
* This function will suspend if no events have been received.
*
* @throws AssertionError if one of the events was completion or an error.
*/
public suspend fun skipItems(count: Int)
/**
* Assert that the next event received was the flow completing.
* This function will suspend if no events have been received.
*
* When this [ReceiveTurbine] is in a terminal state ([Event.Complete] or [Event.Error]), this method
* will yield the same result every time it is called.
*
* @throws AssertionError if the next event was an item or an error.
*/
public suspend fun awaitComplete()
/**
* Assert that the next event received was an error terminating the flow.
* This function will suspend if no events have been received.
*
* When this [ReceiveTurbine] is in a terminal state ([Event.Complete] or [Event.Error]), this method
* will yield the same result every time it is called.
*
* @throws AssertionError if the next event was an item or completion.
*/
public suspend fun awaitError(): Throwable
/**
* Assert that all events that have occurred so far on this [ReceiveTurbine] have been consumed.
*
* [ensureAllEventsConsumed] will execute the same assertion performed internally by [test] and [testIn]
* on the completion of the validation block.
*/
public fun ensureAllEventsConsumed()
}