The following methods have been replaced by APIs in theflutter_test package:

• BinaryMessenger.checkMessageHandler
• BinaryMessenger.setMockMessageHandler
• BinaryMessenger.checkMockMessageHandler
• BasicMessageChannel.setMockMessageHandler
• MethodChannel.checkMethodCallHandler
• MethodChannel.setMockMethodCallHandler
• MethodChannel.checkMockMethodCallHandler

TheonPlatformMessage callback is no longer used by the Flutter framework.

As part of a refactoring of the low-level plugin communications architecture, we have moved from the previousonPlatformMessage/handlePlatformMessage logic to a per-channel buffering system implemented in the engine in theChannelBuffers class. To maintain compatibility with existing code, the existingBinaryMessenger.setMessageHandler API has been refactored to use the newChannelBuffers API.

One difference between theChannelBuffers API and the previous API is that the new API is more consistent in its approach to asynchrony. As a side-effect, the APIs around message passing are now entirely asynchronous.

This posed a problem for the implementation of the legacy testing APIs which, for historical reasons, were previously in theflutter package. Since they relied on the underlying logic being partly synchronous, they required refactoring. To avoid adding even more test logic into theflutter package, a decision was made to move this logic to theflutter_test package.

Specifically, the following APIs were affected:

• BinaryMessenger.checkMessageHandler: Obsolete.
• BinaryMessenger.setMockMessageHandler: Replaced byTestDefaultBinaryMessenger.setMockMessageHandler.
• BinaryMessenger.checkMockMessageHandler: Replaced byTestDefaultBinaryMessenger.checkMockMessageHandler.
• BasicMessageChannel.setMockMessageHandler: Replaced byTestDefaultBinaryMessenger.setMockDecodedMessageHandler.
• MethodChannel.checkMethodCallHandler: Obsolete.
• MethodChannel.setMockMethodCallHandler: Replaced byTestDefaultBinaryMessenger.setMockMethodCallHandler.
• MethodChannel.checkMockMethodCallHandler: Replaced byTestDefaultBinaryMessenger.checkMockMessageHandler.

These replacements are only available to code using the newTestDefaultBinaryMessengerBinding (such as any code usingtestWidgets in aflutter_test test). There is no replacement for production code that was using these APIs, as they were not intended for production code use.

Tests usingcheckMessageHandler have no equivalent in the new API, since message handler registration is handled directly by theChannelBuffers object, which does not expose the currently registered listener for a channel. (Tests verifying handler registration appear to be rare.)

Code that needs migrating may see errors such as the following:

  error - The method 'setMockMessageHandler' isn't defined for the type 'BinaryMessenger' at test/sensors_test.dart:64:8 - (undefined_method)  error • The method 'setMockMethodCallHandler' isn't defined for the type 'MethodChannel' • test/widgets/editable_text_test.dart:5623:30 • undefined_method[error] The method 'setMockMessageHandler' isn't defined for the type 'BasicMessageChannel' (test/material/feedback_test.dart:37:36)

In addition, theonPlatformMessage callback, which previously was hooked by the framework to receive messages from plugins, is no longer used (and will be removed in due course). As a result, calling this callback to inject messages into the framework no longer has an effect.

Theflutter_test package provides some shims so that uses of the obsoletesetMock... andcheckMock... methods will continue to work. Tests that previously did not importpackage:flutter_test/flutter_test.dart can do so to enable these shims; this should be sufficient to migrate most code.

These shim APIs are deprecated, however. Instead, in code usingWidgetTester (for example, usingtestWidgets), it is recommended to use the following patterns to replace calls to those methods (wheretester is theWidgetTester instance):

// old codeServicesBinding.defaultBinaryMessenger.setMockMessageHandler(...);ServicesBinding.defaultBinaryMessenger.checkMockMessageHandler(...);// new codetester.binding.defaultBinaryMessenger.setMockMessageHandler(...);tester.binding.defaultBinaryMessenger.checkMockMessageHandler(...);

// old codemyChannel.setMockMessageHandler(...);myChannel.checkMockMessageHandler(...);// new codetester.binding.defaultBinaryMessenger.setMockDecodedMessageHandler(myChannel,...);tester.binding.defaultBinaryMessenger.checkMockMessageHandler(myChannel,...);

// old codemyMethodChannel.setMockMethodCallHandler(...);myMethodChannel.checkMockMethodCallHandler(...);// new codetester.binding.defaultBinaryMessenger.setMockMethodCallHandler(myMethodChannel,...);tester.binding.defaultBinaryMessenger.checkMockMessageHandler(myMethodChannel,...);

Tests that usepackage:test andtest() can be changed to usepackage:flutter_test andtestWidgets() to get access to aWidgetTester.

Code that does not have access to aWidgetTester can refer toTestDefaultBinaryMessengerBinding.instance!.defaultBinaryMessenger instead oftester.binding.defaultBinaryMessenger.

Tests that do not use the default test widgets binding (AutomatedTestWidgetsFlutterBinding, which is initialized bytestWidgets) can mix theTestDefaultBinaryMessengerBinding mixin into their binding to get the same results.

Tests that manipulateonPlatformMessage will no longer function as designed. To send mock messages to the framework, consider usingChannelBuffers.push. There is no mechanism to intercept messages from the plugins and forward them to the framework in the new API. If your use case requires such a mechanism, please file a bug.

Landed in version: 2.3.0-17.0.pre.1
In stable release: 2.5

API documentation:

• TestDefaultBinaryMessenger
• TestDefaultBinaryMessengerBinding

Relevant PR:

• PR #76288: Migrate to ChannelBuffers.push