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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
// Copyright 2014 The Flutter Authors. 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:ui' as ui;
import 'package:fake_async/fake_async.dart';
import 'package:flutter/services.dart';
/// A function which takes the name of the method channel, it's handler,
/// platform message and asynchronously returns an encoded response.
typedef AllMessagesHandler = Future<ByteData?>? Function(
String channel, MessageHandler? handler, ByteData? message);
/// A [BinaryMessenger] subclass that is used as the default binary messenger
/// under testing environment.
///
/// It tracks status of data sent across the Flutter platform barrier, which is
/// useful for testing frameworks to monitor and synchronize against the
/// platform messages.
///
/// ## Messages from the framework to the platform
///
/// Messages are sent from the framework to the platform via the
/// [send] method.
///
/// To intercept a message sent from the framework to the platform,
/// consider using [setMockMessageHandler],
/// [setMockDecodedMessageHandler], and [setMockMethodCallHandler]
/// (see also [checkMockMessageHandler]).
///
/// To wait for all pending framework-to-platform messages, the
/// [platformMessagesFinished] getter provides an appropriate
/// [Future]. The [pendingMessageCount] getter returns the current
/// number of outstanding messages.
///
/// ## Messages from the platform to the framework
///
/// The platform sends messages via the [ChannelBuffers] API. Mock
/// messages can be sent to the framework using
/// [handlePlatformMessage].
///
/// Listeners for these messages are configured using [setMessageHandler].
class TestDefaultBinaryMessenger extends BinaryMessenger {
/// Creates a [TestDefaultBinaryMessenger] instance.
///
/// The [delegate] instance must not be null.
TestDefaultBinaryMessenger(this.delegate): assert(delegate != null);
/// The delegate [BinaryMessenger].
final BinaryMessenger delegate;
// The handlers for messages from the engine (including fake
// messages sent by handlePlatformMessage).
final Map<String, MessageHandler> _inboundHandlers = <String, MessageHandler>{};
/// Send a mock message to the framework as if it came from the platform.
///
/// If a listener has been set using [setMessageHandler], that listener is
/// invoked to handle the message, and this method returns a future that
/// completes with that handler's result.
///
/// {@template flutter.flutter_test.TestDefaultBinaryMessenger.handlePlatformMessage.asyncHandlers}
/// It is strongly recommended that all handlers used with this API be
/// synchronous (not requiring any microtasks to complete), because
/// [testWidgets] tests run in a [FakeAsync] zone in which microtasks do not
/// progress except when time is explicitly advanced (e.g. with
/// [WidgetTester.pump]), which means that `await`ing a [Future] will result
/// in the test hanging.
/// {@endtemplate}
///
/// If no listener is configured, this method returns right away with null.
///
/// The `callback` argument, if non-null, will be called just before this
/// method's future completes, either with the result of the listener
/// registered with [setMessageHandler], or with null if no listener has
/// been registered.
///
/// Messages can also be sent via [ChannelBuffers.push] (see
/// [ServicesBinding.channelBuffers]); the effect is the same, though that API
/// will not wait for a response.
// TODO(ianh): When the superclass `handlePlatformMessage` is removed,
// remove this @override (but leave the method).
@override
Future<ByteData?> handlePlatformMessage(
String channel,
ByteData? data,
ui.PlatformMessageResponseCallback? callback,
) {
Future<ByteData?>? result;
if (_inboundHandlers.containsKey(channel))
result = _inboundHandlers[channel]!(data);
result ??= Future<ByteData?>.value();
if (callback != null)
result = result.then((ByteData? result) { callback(result); return result; });
return result;
}
@override
void setMessageHandler(String channel, MessageHandler? handler) {
if (handler == null) {
_inboundHandlers.remove(channel);
delegate.setMessageHandler(channel, null);
} else {
_inboundHandlers[channel] = handler; // used to handle fake messages sent via handlePlatformMessage
delegate.setMessageHandler(channel, handler); // used to handle real messages from the engine
}
}
final List<Future<ByteData?>> _pendingMessages = <Future<ByteData?>>[];
/// The number of incomplete/pending calls sent to the platform channels.
int get pendingMessageCount => _pendingMessages.length;
// Handlers that intercept and respond to outgoing messages,
// pretending to be the platform.
final Map<String, MessageHandler> _outboundHandlers = <String, MessageHandler>{};
// The outbound callbacks that were actually registered, so that we
// can implement the [checkMockMessageHandler] method.
final Map<String, Object> _outboundHandlerIdentities = <String, Object>{};
/// Handler that intercepts and responds to outgoing messages, pretending
/// to be the platform, for all channels.
AllMessagesHandler? allMessagesHandler;
@override
Future<ByteData?>? send(String channel, ByteData? message) {
final Future<ByteData?>? resultFuture;
final MessageHandler? handler = _outboundHandlers[channel];
if (allMessagesHandler != null) {
resultFuture = allMessagesHandler!(channel, handler, message);
} else if (handler != null) {
resultFuture = handler(message);
} else {
resultFuture = delegate.send(channel, message);
}
if (resultFuture != null) {
_pendingMessages.add(resultFuture);
resultFuture
.catchError((Object error) { /* errors are the responsibility of the caller */ })
.whenComplete(() => _pendingMessages.remove(resultFuture));
}
return resultFuture;
}
/// Returns a Future that completes after all the platform calls are finished.
///
/// If a new platform message is sent after this method is called, this new
/// message is not tracked. Use with [pendingMessageCount] to guarantee no
/// pending message calls.
Future<void> get platformMessagesFinished {
return Future.wait<void>(_pendingMessages);
}
/// Set a callback for intercepting messages sent to the platform on
/// the given channel, without decoding them.
///
/// Intercepted messages are not forwarded to the platform.
///
/// The given callback will replace the currently registered
/// callback for that channel, if any. To stop intercepting messages
/// at all, pass null as the handler.
///
/// The handler's return value, if non-null, is used as a response,
/// unencoded.
///
/// {@macro flutter.flutter_test.TestDefaultBinaryMessenger.handlePlatformMessage.asyncHandlers}
///
/// The `identity` argument, if non-null, is used to identify the
/// callback when checked by [checkMockMessageHandler]. If null, the
/// `handler` is used instead. (This allows closures to be passed as
/// the `handler` with an alias used as the `identity` so that a
/// reference to the closure need not be used. In practice, this is
/// used by [setMockDecodedMessageHandler] and
/// [setMockMethodCallHandler] to allow [checkMockMessageHandler] to
/// recognize the closures that were passed to those methods even
/// though those methods wrap those closures when passing them to
/// this method.)
///
/// Registered callbacks are cleared after each test.
///
/// See also:
///
/// * [checkMockMessageHandler], which can verify if a handler is still
/// registered, which is useful in tests to ensure that no unexpected
/// handlers are being registered.
///
/// * [setMockDecodedMessageHandler], which wraps this method but
/// decodes the messages using a [MessageCodec].
///
/// * [setMockMethodCallHandler], which wraps this method but decodes
/// the messages using a [MethodCodec].
void setMockMessageHandler(String channel, MessageHandler? handler, [ Object? identity ]) {
if (handler == null) {
_outboundHandlers.remove(channel);
_outboundHandlerIdentities.remove(channel);
} else {
identity ??= handler;
_outboundHandlers[channel] = handler;
_outboundHandlerIdentities[channel] = identity;
}
}
/// Set a callback for intercepting messages sent to the platform on
/// the given channel.
///
/// Intercepted messages are not forwarded to the platform.
///
/// The given callback will replace the currently registered
/// callback for that channel, if any. To stop intercepting messages
/// at all, pass null as the handler.
///
/// Messages are decoded using the codec of the channel.
///
/// The handler's return value, if non-null, is used as a response,
/// after encoding it using the channel's codec.
///
/// {@macro flutter.flutter_test.TestDefaultBinaryMessenger.handlePlatformMessage.asyncHandlers}
///
/// Registered callbacks are cleared after each test.
///
/// See also:
///
/// * [checkMockMessageHandler], which can verify if a handler is still
/// registered, which is useful in tests to ensure that no unexpected
/// handlers are being registered.
///
/// * [setMockMessageHandler], which is similar but provides raw
/// access to the underlying bytes.
///
/// * [setMockMethodCallHandler], which is similar but decodes
/// the messages using a [MethodCodec].
void setMockDecodedMessageHandler<T>(BasicMessageChannel<T> channel, Future<T> Function(T? message)? handler) {
if (handler == null) {
setMockMessageHandler(channel.name, null);
return;
}
setMockMessageHandler(channel.name, (ByteData? message) async {
return channel.codec.encodeMessage(await handler(channel.codec.decodeMessage(message)));
}, handler);
}
/// Set a callback for intercepting method calls sent to the
/// platform on the given channel.
///
/// Intercepted method calls are not forwarded to the platform.
///
/// The given callback will replace the currently registered
/// callback for that channel, if any. To stop intercepting messages
/// at all, pass null as the handler.
///
/// Methods are decoded using the codec of the channel.
///
/// The handler's return value, if non-null, is used as a response,
/// after re-encoding it using the channel's codec.
///
/// To send an error, throw a [PlatformException] in the handler.
/// Other exceptions are not caught.
///
/// {@macro flutter.flutter_test.TestDefaultBinaryMessenger.handlePlatformMessage.asyncHandlers}
///
/// Registered callbacks are cleared after each test.
///
/// See also:
///
/// * [checkMockMessageHandler], which can verify if a handler is still
/// registered, which is useful in tests to ensure that no unexpected
/// handlers are being registered.
///
/// * [setMockMessageHandler], which is similar but provides raw
/// access to the underlying bytes.
///
/// * [setMockDecodedMessageHandler], which is similar but decodes
/// the messages using a [MessageCodec].
void setMockMethodCallHandler(MethodChannel channel, Future<Object?>? Function(MethodCall message)? handler) {
if (handler == null) {
setMockMessageHandler(channel.name, null);
return;
}
setMockMessageHandler(channel.name, (ByteData? message) async {
final MethodCall call = channel.codec.decodeMethodCall(message);
try {
return channel.codec.encodeSuccessEnvelope(await handler(call));
} on PlatformException catch (error) {
return channel.codec.encodeErrorEnvelope(
code: error.code,
message: error.message,
details: error.details,
);
} on MissingPluginException {
return null;
} catch (error) {
return channel.codec.encodeErrorEnvelope(code: 'error', message: '$error');
}
}, handler);
}
/// Returns true if the `handler` argument matches the `handler`
/// previously passed to [setMockMessageHandler],
/// [setMockDecodedMessageHandler], or [setMockMethodCallHandler].
///
/// Specifically, it compares the argument provided to the `identity`
/// argument provided to [setMockMessageHandler], defaulting to the
/// `handler` argument passed to that method is `identity` was null.
///
/// This method is useful for tests or test harnesses that want to assert the
/// mock handler for the specified channel has not been altered by a previous
/// test.
///
/// Passing null for the `handler` returns true if the handler for the
/// `channel` is not set.
///
/// Registered callbacks are cleared after each test.
bool checkMockMessageHandler(String channel, Object? handler) => _outboundHandlerIdentities[channel] == handler;
}