flutter · auto-submit · Sep 27, 2024 · Sep 26, 2024 · Sep 26, 2024 · Sep 26, 2024
diff --git a/packages/flutter/lib/src/widgets/binding.dart b/packages/flutter/lib/src/widgets/binding.dart
@@ -1225,10 +1225,27 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB
   ///
   /// The [View] determines into what [FlutterView] the app is rendered into.
   /// This is currently [PlatformDispatcher.implicitView] from [platformDispatcher].
+  /// This method will throw a [StateError] if the [PlatformDispatcher.implicitView]
+  /// is null.
   ///
   /// The `rootWidget` widget provided to this method must not already be
   /// wrapped in a [View].
   Widget wrapWithDefaultView(Widget rootWidget) {
+    if (platformDispatcher.implicitView == null) {
+      throw StateError(
+        'The app requested a view, but the platform did not provide one.\n'
+        'This is likely because the app called `runApp` to render its root '
+        'widget, which expects the platform to provide a default view to '
+        'render into (the "implicit" view).\n'
+        'However, the platform likely has multi-view mode enabled, which does '
+        'not create this default "implicit" view.\n'
+        'Try using `runWidget` instead of `runApp` to start your app.\n'
+        '`runWidget` allows you to provide a `View` widget, without requiring '
+        'a default view.'
+        '${kIsWeb?"\nSee: https://flutter.dev/to/web-multiview-runwidget" : ""}'
+      );
+    }
+
     return View(
       view: platformDispatcher.implicitView!,
       deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner: pipelineOwner,

diff --git a/packages/flutter/test/widgets/multi_view_no_implicit_view_binding_test.dart b/packages/flutter/test/widgets/multi_view_no_implicit_view_binding_test.dart
@@ -0,0 +1,44 @@
+// 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/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import 'multi_view_testing.dart';
+
+void main() {
+  // Overrides the default test bindings so we have the ability to hide the
+  // implicitView inside the body of a test.
+  final NoImplicitViewWidgetsBinding binding = NoImplicitViewWidgetsBinding();
+
+  testWidgets('NoImplicitViewWidgetsBinding self-test', (WidgetTester tester) async {
+    expect(tester.platformDispatcher.implicitView, isNotNull);
+
+    // Hide the implicitView from the test harness.
+    binding.hideImplicitView();
+
+    expect(tester.platformDispatcher.implicitView, isNull);
+
+    // Ensure the test harness finds the implicitView.
+    binding.showImplicitView();
+  });
+
+  testWidgets('null implicitView - runApp throws assertion, suggests to use `runWidget`.', (WidgetTester tester) async {
+    // Hide the implicitView from the test harness.
+    binding.hideImplicitView();
+
+    expect(() {
+      runApp(Container());
+    }, throwsA(
+        isA<StateError>().having(
+          (StateError error) => error.message,
+          'description',
+          contains('Try using `runWidget` instead of `runApp`'),        ),
+        ),
+    );
+
+    // Ensure the test harness finds the implicitView.
+    binding.showImplicitView();
+  });
+}
diff --git a/packages/flutter/test/widgets/multi_view_testing.dart b/packages/flutter/test/widgets/multi_view_testing.dart
@@ -31,3 +31,48 @@ class FakeView extends TestFlutterView {
     // not produce consistent semantics trees.
   }
 }
+
+/// A test platform dispatcher that can show/hide its underlying `implicitView`,
+/// depending on the value of the [implicitViewHidden] flag.
+class NoImplicitViewPlatformDispatcher extends TestPlatformDispatcher {
+  NoImplicitViewPlatformDispatcher({ required super.platformDispatcher }) : superPlatformDispatcher = platformDispatcher;
+
+  final PlatformDispatcher superPlatformDispatcher;
+
+  bool implicitViewHidden = false;
+
+  @override
+  TestFlutterView? get implicitView {
+    return implicitViewHidden
+        ? null
+        : superPlatformDispatcher.implicitView as TestFlutterView?;
+  }
+}
+
+/// Test Flutter Bindings that allow tests to hide/show the `implicitView`
+/// of their [NoImplicitViewPlatformDispatcher] `platformDispatcher`.
+///
+/// This is used to test that [runApp] throws an assertion error with an
+/// explanation when used when the `implicitView` is disabled (like in Flutter
+/// web when multi-view is enabled).
+///
+/// Because of how [testWidgets] uses `runApp` internally to manage the lifecycle
+/// of a test, the implicitView must be disabled/reenabled inside of the body of
+/// the [WidgetTesterCallback] under test. In practice: the implicitView is disabled
+/// in the first line of the test, and reenabled in the last.
+///
+/// See: multi_view_no_implicitView_binding_test.dart
+class NoImplicitViewWidgetsBinding extends AutomatedTestWidgetsFlutterBinding {
+  late final NoImplicitViewPlatformDispatcher _platformDispatcher = NoImplicitViewPlatformDispatcher(platformDispatcher: super.platformDispatcher);
+
+  @override
+  NoImplicitViewPlatformDispatcher get platformDispatcher => _platformDispatcher;
+
+  void hideImplicitView() {
+    platformDispatcher.implicitViewHidden = true;
+  }
+
+  void showImplicitView() {
+    platformDispatcher.implicitViewHidden = false;
+  }
+}