feat(tools): Arbitrary browser flags (closes #65575) (#104935)

packages/flutter_tools/lib/src/commands/drive.dart

@@ -279,6 +279,7 @@ class DriveCommand extends RunCommandBase {
         packageConfig,
         chromeBinary: stringArgDeprecated('chrome-binary'),
         headless: boolArgDeprecated('headless'),
+        webBrowserFlags: stringsArg(FlutterOptions.kWebBrowserFlag),
         browserDimension: stringArgDeprecated('browser-dimension')!.split(','),
         browserName: stringArgDeprecated('browser-name'),
         driverPort: stringArgDeprecated('driver-port') != null

packages/flutter_tools/lib/src/commands/run.dart

@@ -202,9 +202,12 @@ abstract class RunCommandBase extends FlutterCommand with DeviceBasedDevelopment
   @protected
   Future<DebuggingOptions> createDebuggingOptions(bool webMode) async {
     final BuildInfo buildInfo = await getBuildInfo();
-    final int? browserDebugPort = featureFlags.isWebEnabled && argResults!.wasParsed('web-browser-debug-port')
+    final int? webBrowserDebugPort = featureFlags.isWebEnabled && argResults!.wasParsed('web-browser-debug-port')
       ? int.parse(stringArgDeprecated('web-browser-debug-port')!)
       : null;
+    final List<String> webBrowserFlags = featureFlags.isWebEnabled
+        ? stringsArg(FlutterOptions.kWebBrowserFlag)
+        : const <String>[];
     if (buildInfo.mode.isRelease) {
       return DebuggingOptions.disabled(
         buildInfo,
@@ -216,7 +219,8 @@ abstract class RunCommandBase extends FlutterCommand with DeviceBasedDevelopment
         webUseSseForInjectedClient: featureFlags.isWebEnabled && stringArgDeprecated('web-server-debug-injected-client-protocol') == 'sse',
         webEnableExposeUrl: featureFlags.isWebEnabled && boolArgDeprecated('web-allow-expose-url'),
         webRunHeadless: featureFlags.isWebEnabled && boolArgDeprecated('web-run-headless'),
-        webBrowserDebugPort: browserDebugPort,
+        webBrowserDebugPort: webBrowserDebugPort,
+        webBrowserFlags: webBrowserFlags,
         enableImpeller: enableImpeller,
         uninstallFirst: uninstallFirst,
       );
@@ -253,7 +257,8 @@ abstract class RunCommandBase extends FlutterCommand with DeviceBasedDevelopment
         webUseSseForInjectedClient: featureFlags.isWebEnabled && stringArgDeprecated('web-server-debug-injected-client-protocol') == 'sse',
         webEnableExposeUrl: featureFlags.isWebEnabled && boolArgDeprecated('web-allow-expose-url'),
         webRunHeadless: featureFlags.isWebEnabled && boolArgDeprecated('web-run-headless'),
-        webBrowserDebugPort: browserDebugPort,
+        webBrowserDebugPort: webBrowserDebugPort,
+        webBrowserFlags: webBrowserFlags,
         webEnableExpressionEvaluation: featureFlags.isWebEnabled && boolArgDeprecated('web-enable-expression-evaluation'),
         webLaunchUrl: featureFlags.isWebEnabled ? stringArgDeprecated('web-launch-url') : null,
         vmserviceOutFile: stringArgDeprecated('vmservice-out-file'),

packages/flutter_tools/lib/src/device.dart

@@ -785,6 +785,7 @@ class DebuggingOptions {
     this.webUseSseForInjectedClient = true,
     this.webRunHeadless = false,
     this.webBrowserDebugPort,
+    this.webBrowserFlags = const <String>[],
     this.webEnableExpressionEvaluation = false,
     this.webLaunchUrl,
     this.vmserviceOutFile,
@@ -805,6 +806,7 @@ class DebuggingOptions {
       this.webUseSseForInjectedClient = true,
       this.webRunHeadless = false,
       this.webBrowserDebugPort,
+      this.webBrowserFlags = const <String>[],
       this.webLaunchUrl,
       this.cacheSkSL = false,
       this.traceAllowlist,
@@ -871,6 +873,7 @@ class DebuggingOptions {
     required this.webUseSseForInjectedClient,
     required this.webRunHeadless,
     required this.webBrowserDebugPort,
+    required this.webBrowserFlags,
     required this.webEnableExpressionEvaluation,
     required this.webLaunchUrl,
     required this.vmserviceOutFile,
@@ -930,6 +933,9 @@ class DebuggingOptions {
   /// The port the browser should use for its debugging protocol.
   final int? webBrowserDebugPort;
 
+  /// Arbitrary browser flags.
+  final List<String> webBrowserFlags;
+
   /// Enable expression evaluation for web target.
   final bool webEnableExpressionEvaluation;
 
@@ -983,6 +989,7 @@ class DebuggingOptions {
     'webUseSseForInjectedClient': webUseSseForInjectedClient,
     'webRunHeadless': webRunHeadless,
     'webBrowserDebugPort': webBrowserDebugPort,
+    'webBrowserFlags': webBrowserFlags,
     'webEnableExpressionEvaluation': webEnableExpressionEvaluation,
     'webLaunchUrl': webLaunchUrl,
     'vmserviceOutFile': vmserviceOutFile,
@@ -1027,6 +1034,7 @@ class DebuggingOptions {
       webUseSseForInjectedClient: (json['webUseSseForInjectedClient'] as bool?)!,
       webRunHeadless: (json['webRunHeadless'] as bool?)!,
       webBrowserDebugPort: json['webBrowserDebugPort'] as int?,
+      webBrowserFlags: ((json['webBrowserFlags'] as List<dynamic>?)?.cast<String>())!,
       webEnableExpressionEvaluation: (json['webEnableExpressionEvaluation'] as bool?)!,
       webLaunchUrl: json['webLaunchUrl'] as String?,
       vmserviceOutFile: json['vmserviceOutFile'] as String?,

packages/flutter_tools/lib/src/drive/drive_service.dart

@@ -97,6 +97,7 @@ abstract class DriverService {
     String? browserName,
     bool? androidEmulator,
     int? driverPort,
+    List<String> webBrowserFlags,
     List<String>? browserDimension,
     String? profileMemory,
   });
@@ -254,6 +255,7 @@ class FlutterDriverService extends DriverService {
     String? browserName,
     bool? androidEmulator,
     int? driverPort,
+    List<String> webBrowserFlags = const <String>[],
     List<String>? browserDimension,
     String? profileMemory,
   }) async {

packages/flutter_tools/lib/src/drive/web_driver_service.dart

@@ -136,6 +136,7 @@ class WebDriverService extends DriverService {
     String? browserName,
     bool? androidEmulator,
     int? driverPort,
+    List<String> webBrowserFlags = const <String>[],
     List<String>? browserDimension,
     String? profileMemory,
   }) async {
@@ -144,7 +145,12 @@ class WebDriverService extends DriverService {
     try {
       webDriver = await async_io.createDriver(
         uri: Uri.parse('http://localhost:$driverPort/'),
-        desired: getDesiredCapabilities(browser, headless, chromeBinary),
+        desired: getDesiredCapabilities(
+          browser,
+          headless,
+          webBrowserFlags: webBrowserFlags,
+          chromeBinary: chromeBinary,
+        ),
       );
     } on SocketException catch (error) {
       _logger.printTrace('$error');
@@ -234,10 +240,15 @@ enum Browser {
   safari,
 }
 
-/// Returns desired capabilities for given [browser], [headless] and
-/// [chromeBinary].
+/// Returns desired capabilities for given [browser], [headless], [chromeBinary]
+/// and [webBrowserFlags].
 @visibleForTesting
-Map<String, dynamic> getDesiredCapabilities(Browser browser, bool? headless, [String? chromeBinary]) {
+Map<String, dynamic> getDesiredCapabilities(
+  Browser browser,
+  bool? headless, {
+  List<String> webBrowserFlags = const <String>[],
+  String? chromeBinary,
+}) {
   switch (browser) {
     case Browser.chrome:
       return <String, dynamic>{
@@ -262,6 +273,7 @@ Map<String, dynamic> getDesiredCapabilities(Browser browser, bool? headless, [St
             '--no-sandbox',
             '--no-first-run',
             if (headless!) '--headless',
+            ...webBrowserFlags,
           ],
           'perfLoggingPrefs': <String, String>{
             'traceCategories':
@@ -278,6 +290,7 @@ Map<String, dynamic> getDesiredCapabilities(Browser browser, bool? headless, [St
         'moz:firefoxOptions' : <String, dynamic>{
           'args': <String>[
             if (headless!) '-headless',
+            ...webBrowserFlags,
           ],
           'prefs': <String, dynamic>{
             'dom.file.createInChild': true,
@@ -313,7 +326,10 @@ Map<String, dynamic> getDesiredCapabilities(Browser browser, bool? headless, [St
         'platformName': 'android',
         'goog:chromeOptions': <String, dynamic>{
           'androidPackage': 'com.android.chrome',
-          'args': <String>['--disable-fullscreen'],
+          'args': <String>[
+            '--disable-fullscreen',
+            ...webBrowserFlags,
+          ],
         },
       };
   }

packages/flutter_tools/lib/src/runner/flutter_command.dart

@@ -119,6 +119,7 @@ class FlutterOptions {
   static const String kAssumeInitializeFromDillUpToDate = 'assume-initialize-from-dill-up-to-date';
   static const String kFatalWarnings = 'fatal-warnings';
   static const String kUseApplicationBinary = 'use-application-binary';
+  static const String kWebBrowserFlag = 'web-browser-flag';
 }
 
 /// flutter command categories for usage.
@@ -270,6 +271,15 @@ abstract class FlutterCommand extends Command<void> {
       help: 'The URL to provide to the browser. Defaults to an HTTP URL with the host '
           'name of "--web-hostname", the port of "--web-port", and the path set to "/".',
     );
+    argParser.addMultiOption(
+      FlutterOptions.kWebBrowserFlag,
+      help: 'Additional flag to pass to a browser instance at startup.\n'
+          'Chrome: https://www.chromium.org/developers/how-tos/run-chromium-with-flags/\n'
+          'Firefox: https://wiki.mozilla.org/Firefox/CommandLineOptions\n'
+          'Multiple flags can be passed by repeating "--${FlutterOptions.kWebBrowserFlag}" multiple times.',
+      valueHelp: '--foo=bar',
+      hide: !verboseHelp,
+    );
   }
 
   void usesTargetOption() {

packages/flutter_tools/lib/src/test/flutter_web_platform.dart

@@ -659,6 +659,8 @@ class BrowserManager {
   ///
   /// The browser will start in headless mode if [headless] is true.
   ///
+  /// Add arbitrary browser flags via [webBrowserFlags].
+  ///
   /// The [settings] indicate how to invoke this browser's executable.
   ///
   /// Returns the browser manager, or throws an [ApplicationException] if a
@@ -670,8 +672,13 @@ class BrowserManager {
     Future<WebSocketChannel> future, {
     bool debug = false,
     bool headless = true,
+    List<String> webBrowserFlags = const <String>[],
   }) async {
-    final Chromium chrome = await chromiumLauncher.launch(url.toString(), headless: headless);
+    final Chromium chrome = await chromiumLauncher.launch(
+      url.toString(),
+      headless: headless,
+      webBrowserFlags: webBrowserFlags,
+    );
     final Completer<BrowserManager> completer = Completer<BrowserManager>();
 
     unawaited(chrome.onExit.then((int? browserExitCode) {

packages/flutter_tools/lib/src/web/chrome.dart

@@ -164,11 +164,14 @@ class ChromiumLauncher {
   /// port is picked automatically.
   ///
   /// [skipCheck] does not attempt to make a devtools connection before returning.
+  ///
+  /// [webBrowserFlags] add arbitrary browser flags.
   Future<Chromium> launch(String url, {
     bool headless = false,
     int? debugPort,
     bool skipCheck = false,
     Directory? cacheDir,
+    List<String> webBrowserFlags = const <String>[],
   }) async {
     if (currentCompleter.isCompleted) {
       throwToolExit('Only one instance of chrome can be started.');
@@ -215,6 +218,7 @@ class ChromiumLauncher {
           '--no-sandbox',
           '--window-size=2400,1800',
         ],
+      ...webBrowserFlags,
       url,
     ];
 

packages/flutter_tools/lib/src/web/web_device.dart

@@ -149,6 +149,7 @@ abstract class ChromiumDevice extends Device {
             .childDirectory('chrome-device'),
         headless: debuggingOptions.webRunHeadless,
         debugPort: debuggingOptions.webBrowserDebugPort,
+        webBrowserFlags: debuggingOptions.webBrowserFlags,
       );
     }
     _logger.sendEvent('app.webLaunchUrl', <String, Object>{'url': url, 'launched': launchChrome});

packages/flutter_tools/test/commands.shard/hermetic/drive_test.dart

@@ -354,6 +354,7 @@ class FailingFakeDriverService extends Fake implements DriverService {
       String browserName,
       bool androidEmulator,
       int driverPort,
+      List<String> webBrowserFlags,
       List<String> browserDimension,
       String profileMemory,
     }) async => 1;