Add WidgetsFlutterBinding Assertion to setMethodCallHandler (#88819)

packages/flutter/lib/src/services/platform_channel.dart

@@ -372,6 +372,13 @@ class MethodChannel {
   /// similarly to what happens if no method call handler has been set.
   /// Any other exception results in an error envelope being sent.
   void setMethodCallHandler(Future<dynamic> Function(MethodCall call)? handler) {
+    assert(
+      _binaryMessenger != null || ServicesBinding.instance != null,
+      'Cannot set the method call handler before the binary messenger has been initialized. '
+      'This happens when you call setMethodCallHandler() before the WidgetsFlutterBinding '
+      'has been initialized. You can fix this by either calling WidgetsFlutterBinding.ensureInitialized() '
+      'before this or by passing a custom BinaryMessenger instance to MethodChannel().',
+    );
     binaryMessenger.setMessageHandler(
       name,
       handler == null

packages/flutter/test/services/set_method_call_handler_test.dart

+// 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 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  // We need a separate test file for this test case (instead of including it
+  // in platform_channel_test.dart) since we rely on the WidgetsFlutterBinding
+  // not being initialized and we call ensureInitialized() in the other test
+  // file.
+  test('throws assertion error iff WidgetsFlutterBinding is not yet initialized', () {
+    const MethodChannel methodChannel = MethodChannel('mock');
+
+    // Verify an assertion error is thrown before the binary messenger is
+    // accessed (which would result in a _CastError due to the non-null
+    // assertion). This way we can hint the caller towards how to fix the error.
+    expect(() => methodChannel.setMethodCallHandler(null), throwsAssertionError);
+
+    // Verify the assertion is not thrown once the binding has been initialized.
+    // This cannot be a separate test case since the execution order is random.
+    TestWidgetsFlutterBinding.ensureInitialized();
+    expect(() => methodChannel.setMethodCallHandler(null), returnsNormally);
+  });
+}