From 3800af160e3ae10a3e6b2d34bf1abb3608fc0866 Mon Sep 17 00:00:00 2001
From: Matan Lurey <matan@lurey.org>
Date: Mon, 30 Sep 2024 16:54:52 -0700
Subject: [PATCH 1/5] Refactor run_command and friends.

---
 .../lib/src/commands/run_command.dart         | 242 +++++++++++++--
 .../lib/src/flutter_tool_interop/device.dart  |  65 +++++
 .../flutter_tool_interop/flutter_tool.dart    |  66 +++++
 .../flutter_tool_interop/target_platform.dart | 154 ++++++++++
 tools/engine_tool/lib/src/run_utils.dart      | 162 ----------
 .../external_tools/flutter_tools_test.dart    | 208 +++++++++++++
 .../test/{ => external_tools}/gn_test.dart    |   2 +-
 tools/engine_tool/test/run_command_test.dart  | 276 +++++++++---------
 tools/engine_tool/test/run_target_test.dart   | 197 +++++++++++++
 tools/engine_tool/test/src/matchers.dart      |  92 ++++++
 10 files changed, 1138 insertions(+), 326 deletions(-)
 create mode 100644 tools/engine_tool/lib/src/flutter_tool_interop/device.dart
 create mode 100644 tools/engine_tool/lib/src/flutter_tool_interop/flutter_tool.dart
 create mode 100644 tools/engine_tool/lib/src/flutter_tool_interop/target_platform.dart
 delete mode 100644 tools/engine_tool/lib/src/run_utils.dart
 create mode 100644 tools/engine_tool/test/external_tools/flutter_tools_test.dart
 rename tools/engine_tool/test/{ => external_tools}/gn_test.dart (99%)
 create mode 100644 tools/engine_tool/test/run_target_test.dart
 create mode 100644 tools/engine_tool/test/src/matchers.dart

diff --git a/tools/engine_tool/lib/src/commands/run_command.dart b/tools/engine_tool/lib/src/commands/run_command.dart
index dc015938d58d6..32de7ef18fed1 100644
--- a/tools/engine_tool/lib/src/commands/run_command.dart
+++ b/tools/engine_tool/lib/src/commands/run_command.dart
@@ -5,11 +5,15 @@
 import 'dart:io' show ProcessStartMode;
 
 import 'package:engine_build_configs/engine_build_configs.dart';
+import 'package:meta/meta.dart';
 import 'package:process_runner/process_runner.dart';
 
 import '../build_utils.dart';
+import '../flutter_tool_interop/device.dart';
+import '../flutter_tool_interop/flutter_tool.dart';
+import '../flutter_tool_interop/target_platform.dart';
 import '../label.dart';
-import '../run_utils.dart';
+import '../logger.dart';
 import 'command.dart';
 import 'flags.dart';
 
@@ -21,6 +25,7 @@ final class RunCommand extends CommandBase {
     required Map<String, BuilderConfig> configs,
     super.help = false,
     super.usageLineLength,
+    @visibleForTesting FlutterTool? flutterTool,
   }) {
     // When printing the help/usage for this command, only list all builds
     // when the --verbose flag is supplied.
@@ -41,8 +46,13 @@ final class RunCommand extends CommandBase {
       defaultsTo: environment.hasRbeConfigInTree(),
       help: 'RBE is enabled by default when available.',
     );
+
+    _flutterTool = flutterTool ?? FlutterTool.fromEnvironment(environment);
   }
 
+  /// Flutter tool.
+  late final FlutterTool _flutterTool;
+
   /// List of compatible builds.
   late final List<Build> builds;
 
@@ -58,7 +68,7 @@ Run a Flutter app with a local engine build.
 See `flutter run --help` for a listing
 ''';
 
-  Build? _lookup(String configName) {
+  Build? _findTargetBuild(String configName) {
     final String demangledName = demangleConfigName(environment, configName);
     return builds
         .where((Build build) => build.name == demangledName)
@@ -78,11 +88,11 @@ See `flutter run --help` for a listing
     final String ci =
         mangledName.startsWith('ci') ? mangledName.substring(0, 3) : '';
     if (mangledName.contains('_debug')) {
-      return _lookup('${ci}host_debug');
+      return _findTargetBuild('${ci}host_debug');
     } else if (mangledName.contains('_profile')) {
-      return _lookup('${ci}host_profile');
+      return _findTargetBuild('${ci}host_profile');
     } else if (mangledName.contains('_release')) {
-      return _lookup('${ci}host_release');
+      return _findTargetBuild('${ci}host_release');
     }
     return null;
   }
@@ -114,43 +124,41 @@ See `flutter run --help` for a listing
     return mode;
   }
 
-  late final Future<RunTarget?> _runTarget =
-      detectAndSelectRunTarget(environment, _getDeviceId());
+  late final Future<RunTarget?> _runTarget = (() async {
+    final devices = await _flutterTool.devices();
+    return RunTarget.detectAndSelect(devices, idPrefix: _getDeviceId());
+  })();
 
-  Future<String?> _selectTargetConfig() async {
-    final String configName = argResults![configFlag] as String;
+  Future<String> _selectTargetConfig() async {
+    final configName = argResults![configFlag] as String;
     if (configName.isNotEmpty) {
       return demangleConfigName(environment, configName);
     }
-    final RunTarget? target = await _runTarget;
+    final target = await _runTarget;
     if (target == null) {
       return demangleConfigName(environment, 'host_debug');
     }
-    environment.logger.status(
-        'Building to run on "${target.name}" running ${target.targetPlatform}');
-    return target.buildConfigFor(_getMode());
+
+    final result = target.buildConfigFor(_getMode());
+    environment.logger.status('Building to run on $result');
+    return result;
   }
 
   @override
   Future<int> run() async {
     if (!environment.processRunner.processManager.canRun('flutter')) {
-      environment.logger.error('Cannot find the flutter command in your path');
-      return 1;
+      throw FatalError('Cannot find the "flutter" command in your PATH');
     }
-    final String? configName = await _selectTargetConfig();
-    if (configName == null) {
-      environment.logger.error('Could not find target config');
-      return 1;
-    }
-    final Build? build = _lookup(configName);
-    final Build? hostBuild = _findHostBuild(build);
-    if (build == null) {
-      environment.logger.error('Could not find build $configName');
-      return 1;
+    final configName = await _selectTargetConfig();
+
+    final targetBuild = _findTargetBuild(configName);
+    if (targetBuild == null) {
+      throw FatalError('Could not find build $configName');
     }
+
+    final hostBuild = _findHostBuild(targetBuild);
     if (hostBuild == null) {
-      environment.logger.error('Could not find host build for $configName');
-      return 1;
+      throw FatalError('Could not find host build for $configName');
     }
 
     final bool useRbe = argResults![rbeFlag] as bool;
@@ -162,8 +170,7 @@ See `flutter run --help` for a listing
       if (!useRbe) '--no-rbe',
     ];
     final RunTarget? target = await _runTarget;
-    final List<Label> buildTargetsForShell =
-        target?.buildTargetsForShell() ?? <Label>[];
+    final buildTargetsForShell = target?.buildTargetsForShell ?? [];
 
     final String dashJ = argResults![concurrencyFlag] as String;
     final int? concurrency = int.tryParse(dashJ);
@@ -185,10 +192,10 @@ See `flutter run --help` for a listing
     }
 
     // Now build the target if it isn't the same.
-    if (hostBuild.name != build.name) {
+    if (hostBuild.name != targetBuild.name) {
       r = await runBuild(
         environment,
-        build,
+        targetBuild,
         concurrency: concurrency,
         extraGnArgs: extraGnArgs,
         enableRbe: useRbe,
@@ -199,7 +206,8 @@ See `flutter run --help` for a listing
       }
     }
 
-    final String mangledBuildName = mangleConfigName(environment, build.name);
+    final String mangledBuildName =
+        mangleConfigName(environment, targetBuild.name);
 
     final String mangledHostBuildName =
         mangleConfigName(environment, hostBuild.name);
@@ -227,3 +235,173 @@ See `flutter run --help` for a listing
     return result.exitCode;
   }
 }
+
+/// Metadata about a target to run `flutter run` on.
+///
+/// This class translates between the `flutter devices` output and the build
+/// configurations supported by the engine, including the build targets needed
+/// to build the shell for the target platform.
+@visibleForTesting
+@immutable
+final class RunTarget {
+  /// Construct a run target from a device returned by `flutter devices`.
+  @visibleForTesting
+  const RunTarget.fromDevice(this.device);
+
+  /// Device to run on.
+  final Device device;
+
+  /// Given a list of devices, returns a build target for the first matching.
+  ///
+  /// If [idPrefix] is provided, only devices with an id that starts with the
+  /// prefix will be considered, otherwise the first device is selected. If no
+  /// devices are available, or none match the prefix, `null` is returned.
+  @visibleForTesting
+  static RunTarget? detectAndSelect(
+    Iterable<Device> devices, {
+    String idPrefix = '',
+  }) {
+    if (devices.isEmpty) {
+      return null;
+    }
+    for (final device in devices) {
+      if (idPrefix.isNotEmpty) {
+        if (device.id.startsWith(idPrefix)) {
+          return RunTarget.fromDevice(device);
+        }
+      }
+    }
+    if (idPrefix.isNotEmpty) {
+      return null;
+    }
+    return RunTarget.fromDevice(devices.first);
+  }
+
+  /// Returns the build configuration for the current platform and given [mode].
+  ///
+  /// The [mode] is typically one of `debug`, `profile`, or `release`.
+  ///
+  /// Throws a [FatalError] if the target platform is not supported.
+  String buildConfigFor(String mode) {
+    return switch (device.targetPlatform) {
+      // Supported platforms with known mappings.
+      // -----------------------------------------------------------------------
+      // ANDROID
+      TargetPlatform.androidUnspecified => 'android_$mode',
+      TargetPlatform.androidX86 => 'android_${mode}_x86',
+      TargetPlatform.androidX64 => 'android_${mode}_x64',
+      TargetPlatform.androidArm64 => 'android_${mode}_arm64',
+
+      // DESKTOP (MacOS, Linux, Windows)
+      // We do not support cross-builds, so implicitly assume the host platform.
+      TargetPlatform.darwinUnspecified ||
+      TargetPlatform.darwinX64 ||
+      TargetPlatform.linuxX64 ||
+      TargetPlatform.windowsX64 =>
+        'host_$mode',
+      TargetPlatform.darwinArm64 ||
+      TargetPlatform.linuxArm64 ||
+      TargetPlatform.windowsArm64 =>
+        'host_${mode}_arm64',
+
+      // WEB
+      TargetPlatform.webJavascript => 'chrome_$mode',
+
+      // Unsupported platforms.
+      // -----------------------------------------------------------------------
+      // iOS.
+      // TODO(matanlurey): https://github.com/flutter/flutter/issues/155960
+      TargetPlatform.iOSUnspecified ||
+      TargetPlatform.iOSX64 ||
+      TargetPlatform.iOSArm64 =>
+        throw FatalError(
+          'iOS targets are currently unsupported.\n\nIf you are an '
+          'iOS engine developer, and have a need for this, please either +1 or '
+          'help us implement https://github.com/flutter/flutter/issues/155960.',
+        ),
+
+      // LEGACY ANDROID
+      TargetPlatform.androidArm => throw FatalError(
+          'Legacy Android targets are not supported. '
+          'Please use android-arm64 or android-x64.',
+        ),
+
+      // FUCHSIA
+      TargetPlatform.fuchsiaArm64 ||
+      TargetPlatform.fuchsiaX64 =>
+        throw FatalError('Fuchsia is not supported.'),
+
+      // TESTER
+      TargetPlatform.tester =>
+        throw FatalError('flutter_tester is not supported.'),
+
+      // Platforms that maybe could be supported, but we don't know about.
+      _ => throw FatalError(
+          'Unknown target platform: ${device.targetPlatform.identifier}.\n\nIf '
+          'this is a new platform that should be supported, please file a bug: '
+          'https://github.com/flutter/flutter/issues/new?labels=e:%20engine-tool.',
+        ),
+    };
+  }
+
+  /// Minimal build targets needed to build the shell for the target platform.
+  List<Label> get buildTargetsForShell {
+    return switch (device.targetPlatform) {
+      // Supported platforms with known mappings.
+      // -----------------------------------------------------------------------
+      // ANDROID
+      TargetPlatform.androidUnspecified ||
+      TargetPlatform.androidX86 ||
+      TargetPlatform.androidX64 ||
+      TargetPlatform.androidArm64 =>
+        [Label.parseGn('//flutter/shell/platform/android:android_jar')],
+
+      // iOS.
+      TargetPlatform.iOSUnspecified ||
+      TargetPlatform.iOSX64 ||
+      TargetPlatform.iOSArm64 =>
+        [
+          Label.parseGn('//flutter/shell/platform/darwin/ios:flutter_framework')
+        ],
+
+      // Desktop (MacOS).
+      TargetPlatform.darwinUnspecified ||
+      TargetPlatform.darwinX64 ||
+      TargetPlatform.darwinArm64 =>
+        [
+          Label.parseGn(
+            '//flutter/shell/platform/darwin/macos:flutter_framework',
+          )
+        ],
+
+      // Desktop (Linux).
+      TargetPlatform.linuxX64 || TargetPlatform.linuxArm64 => [
+          Label.parseGn(
+            '//flutter/shell/platform/linux:flutter_linux_gtk',
+          )
+        ],
+
+      // Desktop (Windows).
+      TargetPlatform.windowsX64 || TargetPlatform.windowsArm64 => [
+          Label.parseGn(
+            '//flutter/shell/platform/windows',
+          )
+        ],
+
+      // Web.
+      TargetPlatform.webJavascript => [
+          Label.parseGn(
+            '//flutter/web_sdk:flutter_web_sdk_archive',
+          )
+        ],
+
+      // Unsupported platforms.
+      // -----------------------------------------------------------------------
+      _ => throw FatalError(
+          'Unknown target platform: ${device.targetPlatform.identifier}.\n\nIf '
+          'this is a new platform that should be supported, please file a bug: '
+          'https://github.com/flutter/flutter/issues/new?labels=e:%20engine-tool.',
+        ),
+    };
+  }
+}
diff --git a/tools/engine_tool/lib/src/flutter_tool_interop/device.dart b/tools/engine_tool/lib/src/flutter_tool_interop/device.dart
new file mode 100644
index 0000000000000..990f6bba82de0
--- /dev/null
+++ b/tools/engine_tool/lib/src/flutter_tool_interop/device.dart
@@ -0,0 +1,65 @@
+import 'dart:convert';
+
+import 'package:meta/meta.dart';
+
+import '../typed_json.dart';
+import 'target_platform.dart';
+
+/// A representation of the parsed device from the `flutter devices` command.
+///
+/// See <https://github.com/flutter/flutter/blob/9441f9d48fce1d0b425628731dd6ecab8c8b0826/packages/flutter_tools/lib/src/device.dart#L892-L911>.
+@immutable
+final class Device {
+  /// Creates a device with the given [name], [id], and [targetPlatform].
+  const Device({
+    required this.name,
+    required this.id,
+    required this.targetPlatform,
+  });
+
+  /// Parses a device from the given [json].
+  factory Device.fromJson(Map<String, Object?> json) {
+    return JsonObject(json).map((o) {
+      return Device(
+        name: o.string('name'),
+        id: o.string('id'),
+        targetPlatform: TargetPlatform.parse(o.string('targetPlatform')),
+      );
+    });
+  }
+
+  /// Name of the device.
+  final String name;
+
+  /// Identifier of the device.
+  final String id;
+
+  /// Target platform of the device.
+  final TargetPlatform targetPlatform;
+
+  @override
+  bool operator ==(Object other) {
+    return other is Device &&
+        other.name == name &&
+        other.id == id &&
+        other.targetPlatform == targetPlatform;
+  }
+
+  @override
+  int get hashCode => Object.hash(name, id, targetPlatform);
+
+  /// Converts this device to a JSON object, for use within tests.
+  @visibleForTesting
+  JsonObject toJson() {
+    return JsonObject({
+      'name': name,
+      'id': id,
+      'targetPlatform': targetPlatform.identifier,
+    });
+  }
+
+  @override
+  String toString() {
+    return 'Device ${const JsonEncoder.withIndent('  ').convert(this)}';
+  }
+}
diff --git a/tools/engine_tool/lib/src/flutter_tool_interop/flutter_tool.dart b/tools/engine_tool/lib/src/flutter_tool_interop/flutter_tool.dart
new file mode 100644
index 0000000000000..2c4084f3225b1
--- /dev/null
+++ b/tools/engine_tool/lib/src/flutter_tool_interop/flutter_tool.dart
@@ -0,0 +1,66 @@
+import 'dart:convert';
+
+import '../environment.dart';
+import '../logger.dart';
+import 'device.dart';
+
+/// An interface to the `flutter` command-line tool.
+interface class FlutterTool {
+  /// Creates a new Flutter tool interface using the given [environment].
+  ///
+  /// A `flutter`[^1] binary must exist on the `PATH`.
+  ///
+  /// [^1]: On Windows, the binary is named `flutter.bat`.
+  const FlutterTool.fromEnvironment(this._environment);
+  final Environment _environment;
+
+  String get _toolPath {
+    return _environment.platform.isWindows ? 'flutter.bat' : 'flutter';
+  }
+
+  /// Returns a list of devices available via the `flutter devices` command.
+  Future<List<Device>> devices() async {
+    final result = await _environment.processRunner.runProcess(
+      [
+        _toolPath,
+        'devices',
+        '--machine',
+      ],
+      failOk: true,
+    );
+    if (result.exitCode != 0) {
+      throw FatalError(
+        'Failed to run `flutter devices --machine`.\n\n'
+        'EXITED: ${result.exitCode}\n'
+        'STDOUT:\n${result.stdout}\n'
+        'STDERR:\n${result.stderr}',
+      );
+    }
+    final List<Object?> jsonDevices;
+    try {
+      jsonDevices = jsonDecode(result.stdout) as List<Object?>;
+    } on FormatException catch (e) {
+      throw FatalError(
+        'Failed to parse `flutter devices --machine` output:\n$e\n\n'
+        'STDOUT:\n${result.stdout}',
+      );
+    }
+    final parsedDevices = <Device>[];
+    for (final device in jsonDevices) {
+      if (device is! Map<String, Object?>) {
+        _environment.logger.error(
+          'Skipping device: Expected a JSON Object, but got:\n$device',
+        );
+        continue;
+      }
+      try {
+        parsedDevices.add(Device.fromJson(device));
+      } on FormatException catch (e) {
+        _environment.logger.error(
+          'Skipping device: Failed to parse JSON Object:\n$device\n\n$e',
+        );
+      }
+    }
+    return parsedDevices;
+  }
+}
diff --git a/tools/engine_tool/lib/src/flutter_tool_interop/target_platform.dart b/tools/engine_tool/lib/src/flutter_tool_interop/target_platform.dart
new file mode 100644
index 0000000000000..7306f31e990c9
--- /dev/null
+++ b/tools/engine_tool/lib/src/flutter_tool_interop/target_platform.dart
@@ -0,0 +1,154 @@
+// Copyright 2013 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:meta/meta.dart';
+
+/// Platforms that are supported by the Flutter tool.
+///
+/// This is partially based on the `flutter_tools` `TargetPlatform` class:
+/// <https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/build_info.dart>
+///
+/// This class is used to represent the target platform of a device.
+@immutable
+final class TargetPlatform {
+  const TargetPlatform._(this.identifier);
+
+  /// Android, host architecture left unspecified.
+  static const androidUnspecified = TargetPlatform._('android');
+
+  /// Android ARM.
+  static const androidArm = TargetPlatform._('android-arm');
+
+  /// Android ARM64.
+  static const androidArm64 = TargetPlatform._('android-arm64');
+
+  /// Android x64.
+  static const androidX64 = TargetPlatform._('android-x64');
+
+  /// Android x86.
+  static const androidX86 = TargetPlatform._('android-x86');
+
+  /// Linux ARM64.
+  static const linuxArm64 = TargetPlatform._('linux-arm64');
+
+  /// Linux x64.
+  static const linuxX64 = TargetPlatform._('linux-x64');
+
+  /// Windows ARM64.
+  static const windowsArm64 = TargetPlatform._('windows-arm64');
+
+  /// Windows x64.
+  static const windowsX64 = TargetPlatform._('windows-x64');
+
+  /// Fuchsia ARM64.
+  static const fuchsiaArm64 = TargetPlatform._('fuchsia-arm64');
+
+  /// Fuchsia x64.
+  static const fuchsiaX64 = TargetPlatform._('fuchsia-x64');
+
+  /// Darwin, host architecture left unspecified.
+  static const darwinUnspecified = TargetPlatform._('darwin');
+
+  /// Darwin ARM64.
+  static const darwinArm64 = TargetPlatform._('darwin-arm64');
+
+  /// Darwin x64.
+  static const darwinX64 = TargetPlatform._('darwin-x64');
+
+  /// iOS, host architecture left unspecified.
+  static const iOSUnspecified = TargetPlatform._('ios');
+
+  /// iOS, ARM64.
+  static const iOSArm64 = TargetPlatform._('ios-arm64');
+
+  /// iOS, x64.
+  static const iOSX64 = TargetPlatform._('ios-x64');
+
+  /// Flutter tester.
+  static const tester = TargetPlatform._('flutter-tester');
+
+  /// Web/Javascript.
+  static const webJavascript = TargetPlatform._('web-javascript');
+
+  /// Platforms that are recognized by the Flutter tool.
+  ///
+  /// There is no reason to use or iterate this list in non-test code; to check
+  /// if a platform is recognized, use [tryParse] and check for `null` instead:
+  ///
+  /// ```dart
+  /// final platform = TargetPlatform.tryParse('android-arm');
+  /// if (platform == null) {
+  ///   // Handle unrecognized platform.
+  /// }
+  /// ```
+  @visibleForTesting
+  static const knownPlatforms = [
+    androidUnspecified,
+    androidArm,
+    androidArm64,
+    androidX64,
+    androidX86,
+    linuxArm64,
+    linuxX64,
+    windowsArm64,
+    windowsX64,
+    fuchsiaArm64,
+    fuchsiaX64,
+    darwinUnspecified,
+    darwinArm64,
+    darwinX64,
+    iOSUnspecified,
+    iOSArm64,
+    iOSX64,
+    tester,
+    webJavascript,
+  ];
+
+  /// Parses the [TargetPlatform] for a given [identifier].
+  ///
+  /// Returns `null` if the [identifier] is not recognized.
+  static TargetPlatform? tryParse(String identifier) {
+    for (final platform in knownPlatforms) {
+      if (platform.identifier == identifier) {
+        return platform;
+      }
+    }
+    return null;
+  }
+
+  /// Parses the [TargetPlatform] for a given [identifier].
+  ///
+  /// Throws a [FormatException] if the [identifier] is not recognized.
+  static TargetPlatform parse(String identifier) {
+    final platform = tryParse(identifier);
+    if (platform == null) {
+      throw FormatException(
+        'Unrecognized TargetPlatform. It is possible that "$identifier" is '
+        'a new platform that is recognized by the `flutter` tool, but has not '
+        'been added to engine_tool, or, if this is a test, an intentionally '
+        'unrecognized platform was used.',
+        identifier,
+      );
+    }
+    return platform;
+  }
+
+  /// String-based identifier that is returned by `flutter device --machine`.
+  ///
+  /// See:
+  /// - <https://github.com/flutter/flutter/blob/9441f9d48fce1d0b425628731dd6ecab8c8b0826/packages/flutter_tools/lib/src/device.dart#L878>.
+  /// - <https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/build_info.dart#L736>.
+  final String identifier;
+
+  @override
+  bool operator ==(Object other) {
+    return other is TargetPlatform && other.identifier == identifier;
+  }
+
+  @override
+  int get hashCode => identifier.hashCode;
+
+  @override
+  String toString() => 'TargetPlatform <$identifier>';
+}
diff --git a/tools/engine_tool/lib/src/run_utils.dart b/tools/engine_tool/lib/src/run_utils.dart
deleted file mode 100644
index 3f80b03857b9c..0000000000000
--- a/tools/engine_tool/lib/src/run_utils.dart
+++ /dev/null
@@ -1,162 +0,0 @@
-// Copyright 2013 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:convert';
-
-import 'package:process_runner/process_runner.dart';
-
-import 'environment.dart';
-import 'label.dart';
-import 'typed_json.dart';
-
-const String _targetPlatformKey = 'targetPlatform';
-const String _nameKey = 'name';
-const String _idKey = 'id';
-
-/// Target to run a flutter application on.
-class RunTarget {
-  /// Construct a RunTarget from a JSON map.
-  factory RunTarget.fromJson(Map<String, Object> map) {
-    return JsonObject(map).map(
-        (JsonObject json) => RunTarget._(
-              json.string(_nameKey),
-              json.string(_idKey),
-              json.string(_targetPlatformKey),
-            ), onError: (JsonObject source, JsonMapException e) {
-      throw FormatException(
-          'Failed to parse RunTarget: $e', source.toPrettyString());
-    });
-  }
-
-  RunTarget._(this.name, this.id, this.targetPlatform);
-
-  /// Name of target device.
-  final String name;
-
-  /// Id of target device.
-  final String id;
-
-  /// Target platform of device.
-  final String targetPlatform;
-
-  /// BuildConfig name for compilation mode.
-  String buildConfigFor(String mode) {
-    switch (targetPlatform) {
-      case 'android-arm64':
-        return 'android_${mode}_arm64';
-      case 'darwin':
-        return 'host_$mode';
-      case 'web-javascript':
-        return 'chrome_$mode';
-      default:
-        throw UnimplementedError('No mapping for $targetPlatform');
-    }
-  }
-
-  /// Returns the minimum set of build targets needed to build the shell for
-  /// this target platform.
-  List<Label> buildTargetsForShell() {
-    final List<Label> labels = <Label>[];
-    switch (targetPlatform) {
-      case 'android-arm64':
-      case 'android-arm32':
-        {
-          labels.add(
-              Label.parseGn('//flutter/shell/platform/android:android_jar'));
-          break;
-        }
-      // TODO(cbracken): iOS and MacOS share the same target platform but
-      // have different build targets. For now hard code iOS.
-      case 'darwin':
-        {
-          labels.add(Label.parseGn(
-              '//flutter/shell/platform/darwin/ios:flutter_framework'));
-          break;
-        }
-      default:
-        throw UnimplementedError('No mapping for $targetPlatform');
-      // For the future:
-      // //flutter/shell/platform/darwin/macos:flutter_framework
-      // //flutter/shell/platform/linux:flutter_linux_gtk
-      // //flutter/shell/platform/windows
-      // //flutter/web_sdk:flutter_web_sdk_archive
-    }
-    return labels;
-  }
-}
-
-/// Parse the raw output of `flutter devices --machine`.
-List<RunTarget> parseDevices(Environment env, String flutterDevicesMachine) {
-  late final List<dynamic> decoded;
-  try {
-    decoded = jsonDecode(flutterDevicesMachine) as List<dynamic>;
-  } on FormatException catch (e) {
-    env.logger.error(
-        'Failed to parse flutter devices output: $e\n\n$flutterDevicesMachine\n\n');
-    return <RunTarget>[];
-  }
-
-  final List<RunTarget> r = <RunTarget>[];
-  for (final dynamic device in decoded) {
-    if (device is! Map<String, Object?>) {
-      return <RunTarget>[];
-    }
-    if (!device.containsKey(_nameKey) || !device.containsKey(_idKey)) {
-      env.logger.error('device is missing required fields:\n$device\n');
-      return <RunTarget>[];
-    }
-    if (!device.containsKey(_targetPlatformKey)) {
-      env.logger.warning('Skipping ${device[_nameKey]}: '
-          'Could not find $_targetPlatformKey in device description.');
-      continue;
-    }
-    late final RunTarget target;
-    try {
-      target = RunTarget.fromJson(device.cast<String, Object>());
-    } on FormatException catch (e) {
-      env.logger.error(e);
-      return <RunTarget>[];
-    }
-    r.add(target);
-  }
-
-  return r;
-}
-
-/// Return the default device to be used.
-RunTarget? defaultDevice(Environment env, List<RunTarget> targets) {
-  if (targets.isEmpty) {
-    return null;
-  }
-  return targets.first;
-}
-
-/// Select a run target.
-RunTarget? selectRunTarget(Environment env, String flutterDevicesMachine,
-    [String? idPrefix]) {
-  final List<RunTarget> targets = parseDevices(env, flutterDevicesMachine);
-  if (idPrefix != null && idPrefix.isNotEmpty) {
-    for (final RunTarget target in targets) {
-      if (target.id.startsWith(idPrefix)) {
-        return target;
-      }
-    }
-  }
-  return defaultDevice(env, targets);
-}
-
-/// Detects available targets and then selects one.
-Future<RunTarget?> detectAndSelectRunTarget(Environment env,
-    [String? idPrefix]) async {
-  final ProcessRunnerResult result = await env.processRunner
-      .runProcess(<String>['flutter', 'devices', '--machine']);
-  if (result.exitCode != 0) {
-    env.logger.error('flutter devices --machine failed:\n'
-        'EXIT_CODE:${result.exitCode}\n'
-        'STDOUT:\n${result.stdout}'
-        'STDERR:\n${result.stderr}');
-    return null;
-  }
-  return selectRunTarget(env, result.stdout, idPrefix);
-}
diff --git a/tools/engine_tool/test/external_tools/flutter_tools_test.dart b/tools/engine_tool/test/external_tools/flutter_tools_test.dart
new file mode 100644
index 0000000000000..4a080038b7716
--- /dev/null
+++ b/tools/engine_tool/test/external_tools/flutter_tools_test.dart
@@ -0,0 +1,208 @@
+// Copyright 2013 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:convert';
+
+import 'package:engine_tool/src/flutter_tool_interop/device.dart';
+import 'package:engine_tool/src/flutter_tool_interop/flutter_tool.dart';
+import 'package:engine_tool/src/flutter_tool_interop/target_platform.dart';
+import 'package:engine_tool/src/logger.dart';
+import 'package:test/test.dart';
+
+import '../src/matchers.dart';
+import '../utils.dart';
+
+void main() {
+  test('devices handles a non-zero exit code', () async {
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          exitCode: 1,
+          stdout: 'stdout',
+          stderr: 'stderr',
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    expect(
+      () => flutterTool.devices(),
+      throwsA(
+        isA<FatalError>().having(
+          (a) => a.toString(),
+          'toString()',
+          allOf([
+            contains('Failed to run'),
+            contains('EXITED: 1'),
+            contains('STDOUT:\nstdout'),
+            contains('STDERR:\nstderr'),
+          ]),
+        ),
+      ),
+    );
+  });
+
+  test('devices handles unparseable data', () async {
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          stdout: 'not json',
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    expect(
+      () => flutterTool.devices(),
+      throwsA(
+        isA<FatalError>().having(
+          (a) => a.toString(),
+          'toString()',
+          allOf([
+            contains('Failed to parse'),
+            contains('STDOUT:\nnot json'),
+          ]),
+        ),
+      ),
+    );
+  });
+
+  test('parses a single device successfully', () async {
+    const testAndroidArm64Device = Device(
+      name: 'test_device',
+      id: 'test_id',
+      targetPlatform: TargetPlatform.androidArm64,
+    );
+
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          stdout: jsonEncode([testAndroidArm64Device]),
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    final devices = await flutterTool.devices();
+    expect(devices, equals([testAndroidArm64Device]));
+  });
+
+  test('parses multiple devices successfully', () async {
+    const testAndroidArm64Device = Device(
+      name: 'test_device',
+      id: 'test_id',
+      targetPlatform: TargetPlatform.androidArm64,
+    );
+    const testIosArm64Device = Device(
+      name: 'test_ios_device',
+      id: 'test_ios_id',
+      targetPlatform: TargetPlatform.iOSArm64,
+    );
+
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          stdout: jsonEncode([testAndroidArm64Device, testIosArm64Device]),
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    final devices = await flutterTool.devices();
+    expect(devices, equals([testAndroidArm64Device, testIosArm64Device]));
+  });
+
+  test('skips entry that is not a JSON map and emits a log error', () async {
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          stdout: jsonEncode([
+            'not a map',
+          ]),
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    final devices = await flutterTool.devices();
+    expect(devices, isEmpty);
+
+    expect(
+      testEnv.testLogs,
+      contains(logRecord(
+        contains('Skipping device: Expected a JSON Object'),
+        level: Logger.errorLevel,
+      )),
+    );
+  });
+
+  test('skips entry that is missing an expected property', () async {
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          stdout: jsonEncode([
+            <String, Object?>{
+              'name': 'test_device',
+              'id': 'test_id',
+            },
+          ]),
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    final devices = await flutterTool.devices();
+    expect(devices, isEmpty);
+
+    expect(
+      testEnv.testLogs,
+      contains(logRecord(
+        contains('Skipping device: Failed to parse JSON Object'),
+        level: Logger.errorLevel,
+      )),
+    );
+  });
+
+  test('skips entry with an unrecognized targetPlatform', () async {
+    final testEnv = TestEnvironment.withTestEngine(
+      cannedProcesses: [
+        CannedProcess(
+          (List<String> command) => command.contains('devices'),
+          stdout: jsonEncode([
+            <String, Object?>{
+              'name': 'test_device',
+              'id': 'test_id',
+              'targetPlatform': 'unknown',
+            },
+          ]),
+        ),
+      ],
+    );
+    addTearDown(testEnv.cleanup);
+
+    final flutterTool = FlutterTool.fromEnvironment(testEnv.environment);
+    final devices = await flutterTool.devices();
+    expect(devices, isEmpty);
+
+    expect(
+      testEnv.testLogs,
+      contains(logRecord(
+        contains('Unrecognized TargetPlatform'),
+        level: Logger.errorLevel,
+      )),
+    );
+  });
+}
diff --git a/tools/engine_tool/test/gn_test.dart b/tools/engine_tool/test/external_tools/gn_test.dart
similarity index 99%
rename from tools/engine_tool/test/gn_test.dart
rename to tools/engine_tool/test/external_tools/gn_test.dart
index 192b66cdc35a8..d0b7a34b1f24b 100644
--- a/tools/engine_tool/test/gn_test.dart
+++ b/tools/engine_tool/test/external_tools/gn_test.dart
@@ -7,7 +7,7 @@ import 'package:engine_tool/src/label.dart';
 import 'package:engine_tool/src/logger.dart';
 import 'package:test/test.dart';
 
-import 'utils.dart';
+import '../utils.dart';
 
 void main() {
   test('gn.desc handles a non-zero exit code', () async {
diff --git a/tools/engine_tool/test/run_command_test.dart b/tools/engine_tool/test/run_command_test.dart
index 1bf2d3094e1ce..c580776efa97a 100644
--- a/tools/engine_tool/test/run_command_test.dart
+++ b/tools/engine_tool/test/run_command_test.dart
@@ -2,17 +2,18 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'dart:convert' as convert;
-import 'dart:ffi' as ffi show Abi;
+import 'dart:convert' show jsonDecode;
+import 'dart:ffi';
 import 'dart:io' as io;
 
+import 'package:args/command_runner.dart';
 import 'package:engine_build_configs/engine_build_configs.dart';
 import 'package:engine_repo_tools/engine_repo_tools.dart';
-import 'package:engine_tool/src/commands/command_runner.dart';
+import 'package:engine_tool/src/commands/run_command.dart';
 import 'package:engine_tool/src/environment.dart';
-import 'package:engine_tool/src/label.dart';
+import 'package:engine_tool/src/flutter_tool_interop/device.dart';
+import 'package:engine_tool/src/flutter_tool_interop/flutter_tool.dart';
 import 'package:engine_tool/src/logger.dart';
-import 'package:engine_tool/src/run_utils.dart';
 import 'package:platform/platform.dart';
 import 'package:process_fakes/process_fakes.dart';
 import 'package:process_runner/process_runner.dart';
@@ -21,158 +22,171 @@ import 'package:test/test.dart';
 import 'fixtures.dart' as fixtures;
 
 void main() {
-  final Engine engine;
-  try {
-    engine = Engine.findWithin();
-  } catch (e) {
-    io.stderr.writeln(e);
-    io.exitCode = 1;
-    return;
-  }
-
-  final BuilderConfig linuxTestConfig = BuilderConfig.fromJson(
+  final linuxTestConfig = BuilderConfig.fromJson(
     path: 'ci/builders/linux_test_config.json',
-    map: convert.jsonDecode(fixtures.testConfig('Linux', Platform.linux))
+    map: jsonDecode(fixtures.testConfig('Linux', Platform.linux))
         as Map<String, Object?>,
   );
 
-  final BuilderConfig macTestConfig = BuilderConfig.fromJson(
+  final macTestConfig = BuilderConfig.fromJson(
     path: 'ci/builders/mac_test_config.json',
-    map: convert.jsonDecode(fixtures.testConfig('Mac-12', Platform.macOS))
+    map: jsonDecode(fixtures.testConfig('Mac-12', Platform.macOS))
         as Map<String, Object?>,
   );
 
-  final BuilderConfig winTestConfig = BuilderConfig.fromJson(
+  final winTestConfig = BuilderConfig.fromJson(
     path: 'ci/builders/win_test_config.json',
-    map: convert.jsonDecode(fixtures.testConfig('Windows-11', Platform.windows))
+    map: jsonDecode(fixtures.testConfig('Windows-11', Platform.windows))
         as Map<String, Object?>,
   );
 
-  final Map<String, BuilderConfig> configs = <String, BuilderConfig>{
+  final allTestConfigs = <String, BuilderConfig>{
     'linux_test_config': linuxTestConfig,
     'mac_test_config': macTestConfig,
     'win_test_config': winTestConfig,
   };
 
-  (Environment, List<List<String>>) linuxEnv(Logger logger) {
-    final List<List<String>> runHistory = <List<String>>[];
-    return (
-      Environment(
-        abi: ffi.Abi.linuxX64,
-        engine: engine,
-        platform: FakePlatform(
-          operatingSystem: Platform.linux,
-          resolvedExecutable: io.Platform.resolvedExecutable,
-          pathSeparator: '/',
-          numberOfProcessors: 32,
-        ),
-        processRunner: ProcessRunner(
-          processManager: FakeProcessManager(onStart: (List<String> command) {
-            runHistory.add(command);
-            switch (command) {
-              case ['flutter', 'devices', '--machine']:
-                return FakeProcess(stdout: fixtures.attachedDevices());
-              default:
-                return FakeProcess();
-            }
-          }, onRun: (List<String> command) {
-            // Should not be executed.
-            assert(false);
-            return io.ProcessResult(81, 1, '', '');
-          }),
-        ),
-        logger: logger,
-      ),
-      runHistory
-    );
-  }
+  late io.Directory tempRoot;
+  late TestEngine testEngine;
 
-  test('run command invokes flutter run', () async {
-    final Logger logger = Logger.test((_) {});
-    final (Environment env, List<List<String>> runHistory) = linuxEnv(logger);
-    final ToolCommandRunner runner = ToolCommandRunner(
-      environment: env,
-      configs: configs,
-    );
-    final int result =
-        await runner.run(<String>['run', '--', '--weird_argument']);
-    expect(result, equals(0));
-    expect(runHistory.length, greaterThanOrEqualTo(6));
-    expect(runHistory[5],
-        containsAllInOrder(<String>['flutter', 'run', '--weird_argument']));
+  setUp(() {
+    tempRoot = io.Directory.systemTemp.createTempSync('engine_tool_test');
+    testEngine = TestEngine.createTemp(rootDir: tempRoot);
   });
 
-  test('parse devices list', () async {
-    final Logger logger = Logger.test((_) {});
-    final (Environment env, _) = linuxEnv(logger);
-    final List<RunTarget> targets =
-        parseDevices(env, fixtures.attachedDevices());
-    expect(targets.length, equals(4));
-    final RunTarget android = targets[0];
-    expect(android.name, contains('gphone64'));
-    expect(android.buildConfigFor('debug'), equals('android_debug_arm64'));
+  tearDown(() {
+    tempRoot.deleteSync(recursive: true);
   });
 
-  test('target specific shell build', () async {
-    final Logger logger = Logger.test((_) {});
-    final (Environment env, _) = linuxEnv(logger);
-    final List<RunTarget> targets =
-        parseDevices(env, fixtures.attachedDevices());
-    final RunTarget android = targets[0];
-    expect(android.name, contains('gphone64'));
-    final List<Label> shellLabels = <Label>[
-      Label.parseGn('//flutter/shell/platform/android:android_jar')
-    ];
-    expect(android.buildTargetsForShell(), equals(shellLabels));
-  });
+  test('fails if flutter is not on your PATH', () async {
+    final failsCanRun = FakeProcessManager(
+      canRun: (executable, {workingDirectory}) {
+        if (executable == 'flutter') {
+          return false;
+        }
+        fail('Unexpected');
+      },
+    );
 
-  test('default device', () async {
-    final Logger logger = Logger.test((_) {});
-    final (Environment env, _) = linuxEnv(logger);
-    final List<RunTarget> targets =
-        parseDevices(env, fixtures.attachedDevices());
-    expect(targets.length, equals(4));
-    final RunTarget? defaultTarget = defaultDevice(env, targets);
-    expect(defaultTarget, isNotNull);
-    expect(defaultTarget!.name, contains('gphone64'));
-    expect(
-        defaultTarget.buildConfigFor('debug'), equals('android_debug_arm64'));
-  });
+    final testEnvironment = Environment(
+      abi: Abi.current(),
+      engine: testEngine,
+      logger: Logger.test((_) {}),
+      platform: _fakePlatform(Platform.linux),
+      processRunner: ProcessRunner(
+        defaultWorkingDirectory: tempRoot,
+        processManager: failsCanRun,
+      ),
+    );
+
+    final et = _engineTool(
+      RunCommand(
+        environment: testEnvironment,
+        configs: {},
+      ),
+    );
 
-  test('device select', () async {
-    final Logger logger = Logger.test((_) {});
-    final (Environment env, _) = linuxEnv(logger);
-    RunTarget target = selectRunTarget(env, fixtures.attachedDevices())!;
-    expect(target.name, contains('gphone64'));
-    target = selectRunTarget(env, fixtures.attachedDevices(), 'mac')!;
-    expect(target.name, contains('macOS'));
+    expect(
+      () => et.run(['run']),
+      throwsA(
+        isA<FatalError>().having(
+          (a) => a.toString(),
+          'toString()',
+          contains('"flutter" command in your PATH'),
+        ),
+      ),
+    );
   });
 
-  test('flutter run device select', () async {
-    final Logger logger = Logger.test((_) {});
-    final (Environment env, List<List<String>> runHistory) = linuxEnv(logger);
-    final ToolCommandRunner runner = ToolCommandRunner(
-      environment: env,
-      configs: configs,
+  group('configuration failures', () {
+    final unusedProcessManager = FakeProcessManager(
+      canRun: (_, {workingDirectory}) => true,
     );
-    // Request that the emulator device is used. The emulator is an Android
-    // ARM64 device.
-    final int result =
-        await runner.run(<String>['run', '--', '-d', 'emulator']);
-    expect(result, equals(0));
-    expect(runHistory.length, greaterThanOrEqualTo(6));
-    // Observe that we selected android_debug_arm64 as the target.
-    expect(
-        runHistory[5],
-        containsAllInOrder(<String>[
-          'flutter',
-          'run',
-          '--local-engine',
-          'android_debug_arm64',
-          '--local-engine-host',
-          'host_debug',
-          '-d',
-          'emulator'
-        ]));
+
+    late List<LogRecord> testLogs;
+    late Environment testEnvironment;
+    late _FakeFlutterTool flutterTool;
+
+    setUp(() {
+      testLogs = [];
+      testEnvironment = Environment(
+        abi: Abi.current(),
+        engine: testEngine,
+        logger: Logger.test(testLogs.add),
+        platform: _fakePlatform(Platform.linux),
+        processRunner: ProcessRunner(
+          defaultWorkingDirectory: tempRoot,
+          processManager: unusedProcessManager,
+        ),
+      );
+      flutterTool = _FakeFlutterTool();
+    });
+
+    test('fails if a target build could not be found', () async {
+      final et = _engineTool(RunCommand(
+        environment: testEnvironment,
+        configs: allTestConfigs,
+        flutterTool: flutterTool,
+      ));
+
+      expect(
+        () => et.run(['run', '--config=android_debug_arm64']),
+        throwsA(
+          isA<FatalError>().having(
+            (a) => a.toString(),
+            'toString()',
+            contains('Could not find build'),
+          ),
+        ),
+      );
+    });
+
+    test('fails if a host build could not be found', () async {
+      final et = _engineTool(RunCommand(
+        environment: testEnvironment,
+        configs: allTestConfigs,
+        flutterTool: flutterTool,
+      ));
+
+      expect(
+        () => et.run(['run', '--config=android_debug_arm64']),
+        throwsA(
+          isA<FatalError>().having(
+            (a) => a.toString(),
+            'toString()',
+            contains('Could not find build'),
+          ),
+        ),
+      );
+    });
   });
 }
+
+CommandRunner<int> _engineTool(RunCommand runCommand) {
+  return CommandRunner<int>(
+    'et',
+    'Fake tool with a single instrumented command.',
+  )..addCommand(runCommand);
+}
+
+Platform _fakePlatform(
+  String os, {
+  int numberOfProcessors = 32,
+  String pathSeparator = '/',
+}) {
+  return FakePlatform(
+    operatingSystem: os,
+    resolvedExecutable: io.Platform.resolvedExecutable,
+    numberOfProcessors: numberOfProcessors,
+    pathSeparator: pathSeparator,
+  );
+}
+
+final class _FakeFlutterTool implements FlutterTool {
+  List<Device> respondWithDevices = [];
+
+  @override
+  Future<List<Device>> devices() async {
+    return respondWithDevices;
+  }
+}
diff --git a/tools/engine_tool/test/run_target_test.dart b/tools/engine_tool/test/run_target_test.dart
new file mode 100644
index 0000000000000..1a26d237128d7
--- /dev/null
+++ b/tools/engine_tool/test/run_target_test.dart
@@ -0,0 +1,197 @@
+// Copyright 2013 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:engine_tool/src/commands/run_command.dart';
+import 'package:engine_tool/src/flutter_tool_interop/device.dart';
+import 'package:engine_tool/src/flutter_tool_interop/target_platform.dart';
+import 'package:engine_tool/src/label.dart';
+import 'package:test/test.dart';
+
+import 'src/matchers.dart';
+
+void main() {
+  group('detectAndSelect', () {
+    test('returns null on an empty list', () {
+      final target = RunTarget.detectAndSelect([]);
+      expect(target, isNull);
+    });
+
+    test('returns the only target', () {
+      final device = _device(TargetPlatform.androidArm64);
+
+      final target = RunTarget.detectAndSelect([device]);
+      expect(
+        target,
+        isA<RunTarget>().having((t) => t.device, 'device', device),
+      );
+    });
+
+    test('returns the first target if multiple are available', () {
+      final device1 = _device(TargetPlatform.androidArm64);
+      final device2 = _device(TargetPlatform.androidX64);
+
+      final target = RunTarget.detectAndSelect([device1, device2]);
+      expect(
+        target,
+        isA<RunTarget>().having((t) => t.device, 'device', device1),
+      );
+    });
+
+    test('returns the android target', () {
+      final device1 = _device(TargetPlatform.darwinArm64);
+      final device2 = _device(TargetPlatform.androidArm64);
+
+      final target = RunTarget.detectAndSelect(
+        [device1, device2],
+        idPrefix: 'android',
+      );
+      expect(
+        target,
+        isA<RunTarget>().having((t) => t.device, 'device', device2),
+      );
+    });
+
+    test('returns the first android target', () {
+      final device1 = _device(TargetPlatform.androidArm64);
+      final device2 = _device(TargetPlatform.androidX64);
+
+      final target = RunTarget.detectAndSelect(
+        [device1, device2],
+        idPrefix: 'android',
+      );
+      expect(
+        target,
+        isA<RunTarget>().having((t) => t.device, 'device', device1),
+      );
+    });
+
+    test('returns null if no android targets are available', () {
+      final device1 = _device(TargetPlatform.darwinArm64);
+      final device2 = _device(TargetPlatform.darwinX64);
+
+      final target = RunTarget.detectAndSelect(
+        [device1, device2],
+        idPrefix: 'android',
+      );
+      expect(target, isNull);
+    });
+  });
+
+  group('buildConfigFor', () {
+    final expectedDebugTargets = {
+      TargetPlatform.androidUnspecified: 'android_debug',
+      TargetPlatform.androidX86: 'android_debug_x86',
+      TargetPlatform.androidX64: 'android_debug_x64',
+      TargetPlatform.androidArm64: 'android_debug_arm64',
+      TargetPlatform.darwinUnspecified: 'host_debug',
+      TargetPlatform.darwinX64: 'host_debug',
+      TargetPlatform.darwinArm64: 'host_debug_arm64',
+      TargetPlatform.linuxX64: 'host_debug',
+      TargetPlatform.linuxArm64: 'host_debug_arm64',
+      TargetPlatform.windowsX64: 'host_debug',
+      TargetPlatform.windowsArm64: 'host_debug_arm64',
+      TargetPlatform.webJavascript: 'chrome_debug',
+    };
+
+    for (final platform in TargetPlatform.knownPlatforms) {
+      if (expectedDebugTargets.containsKey(platform)) {
+        test('${platform.identifier} => ${expectedDebugTargets[platform]}', () {
+          final device = _device(platform);
+          final target = RunTarget.fromDevice(device);
+
+          expect(
+            target.buildConfigFor('debug'),
+            expectedDebugTargets[platform],
+          );
+        });
+      } else {
+        test('${platform.identifier} => FatalError', () {
+          final device = _device(platform);
+          final target = RunTarget.fromDevice(device);
+
+          expect(() => target.buildConfigFor('debug'), throwsFatalError);
+        });
+      }
+    }
+  });
+
+  group('buildTargetsForShell', () {
+    final expectedShellTargets = {
+      TargetPlatform.androidUnspecified: [
+        Label.parseGn('//flutter/shell/platform/android:android_jar')
+      ],
+      TargetPlatform.androidX86: [
+        Label.parseGn('//flutter/shell/platform/android:android_jar')
+      ],
+      TargetPlatform.androidX64: [
+        Label.parseGn('//flutter/shell/platform/android:android_jar')
+      ],
+      TargetPlatform.androidArm64: [
+        Label.parseGn('//flutter/shell/platform/android:android_jar')
+      ],
+      TargetPlatform.iOSUnspecified: [
+        Label.parseGn('//flutter/shell/platform/darwin/ios:flutter_framework')
+      ],
+      TargetPlatform.iOSX64: [
+        Label.parseGn('//flutter/shell/platform/darwin/ios:flutter_framework')
+      ],
+      TargetPlatform.iOSArm64: [
+        Label.parseGn('//flutter/shell/platform/darwin/ios:flutter_framework')
+      ],
+      TargetPlatform.darwinUnspecified: [
+        Label.parseGn('//flutter/shell/platform/darwin/macos:flutter_framework')
+      ],
+      TargetPlatform.darwinX64: [
+        Label.parseGn('//flutter/shell/platform/darwin/macos:flutter_framework')
+      ],
+      TargetPlatform.darwinArm64: [
+        Label.parseGn('//flutter/shell/platform/darwin/macos:flutter_framework')
+      ],
+      TargetPlatform.linuxX64: [
+        Label.parseGn('//flutter/shell/platform/linux:flutter_linux_gtk')
+      ],
+      TargetPlatform.linuxArm64: [
+        Label.parseGn('//flutter/shell/platform/linux:flutter_linux_gtk')
+      ],
+      TargetPlatform.windowsX64: [
+        Label.parseGn('//flutter/shell/platform/windows')
+      ],
+      TargetPlatform.windowsArm64: [
+        Label.parseGn('//flutter/shell/platform/windows')
+      ],
+      TargetPlatform.webJavascript: [
+        Label.parseGn('//flutter/web_sdk:flutter_web_sdk_archive')
+      ],
+    };
+
+    for (final platform in TargetPlatform.knownPlatforms) {
+      if (expectedShellTargets.containsKey(platform)) {
+        test('${platform.identifier} => ${expectedShellTargets[platform]}', () {
+          final device = _device(platform);
+          final target = RunTarget.fromDevice(device);
+
+          expect(
+            target.buildTargetsForShell,
+            expectedShellTargets[platform],
+          );
+        });
+      } else {
+        test('${platform.identifier} => FatalError', () {
+          final device = _device(platform);
+          final target = RunTarget.fromDevice(device);
+
+          expect(() => target.buildTargetsForShell, throwsFatalError);
+        });
+      }
+    }
+  });
+}
+
+Device _device(TargetPlatform platform) {
+  return Device(
+    name: 'Test Device <${platform.identifier}>',
+    id: platform.identifier,
+    targetPlatform: platform,
+  );
+}
diff --git a/tools/engine_tool/test/src/matchers.dart b/tools/engine_tool/test/src/matchers.dart
new file mode 100644
index 0000000000000..b27d5c722e51f
--- /dev/null
+++ b/tools/engine_tool/test/src/matchers.dart
@@ -0,0 +1,92 @@
+import 'package:engine_tool/src/logger.dart';
+import 'package:logging/logging.dart';
+import 'package:test/test.dart';
+
+/// Matches a thrown [FatalError].
+final throwsFatalError = throwsA(isA<FatalError>());
+
+/// Returns a matcher that matches a [LogRecord] with a [message].
+///
+/// If [message] is a [String], it uses [equals] to match the message, otherwise
+/// [message] must be a subtype of [Matcher].
+///
+/// Optionally, you can provide a [level] to match the log level, which defaults
+/// to [anything], but can otherwise either be a [Level] or a subtype of
+/// [Matcher].
+Matcher logRecord(Object message, {Object level = anything}) {
+  final Matcher messageMatcher = switch (message) {
+    String() => equals(message),
+    Matcher() => message,
+    _ => throw ArgumentError.value(
+        message,
+        'message',
+        'must be a String or Matcher',
+      ),
+  };
+  final Matcher levelMatcher = switch (level) {
+    Level() => equals(level),
+    Matcher() => level,
+    _ => throw ArgumentError.value(
+        level,
+        'level',
+        'must be a Level or Matcher',
+      ),
+  };
+  return _LogRecordMatcher(levelMatcher, messageMatcher);
+}
+
+final class _LogRecordMatcher extends Matcher {
+  _LogRecordMatcher(this._levelMatcher, this._messageMatcher);
+  final Matcher _levelMatcher;
+  final Matcher _messageMatcher;
+
+  @override
+  bool matches(Object? item, Map<Object?, Object?> matchState) {
+    if (item is! LogRecord) {
+      return false;
+    }
+    if (!_levelMatcher.matches(item.level, matchState)) {
+      return false;
+    }
+    if (!_messageMatcher.matches(item.message, matchState)) {
+      return false;
+    }
+    return true;
+  }
+
+  @override
+  Description describe(Description description) {
+    return description
+        .add('LogRecord with level matching ')
+        .addDescriptionOf(_levelMatcher)
+        .add(' and message matching ')
+        .addDescriptionOf(_messageMatcher);
+  }
+
+  @override
+  Description describeMismatch(
+    Object? item,
+    Description mismatchDescription,
+    Map<Object?, Object?> matchState,
+    bool verbose,
+  ) {
+    if (item is! LogRecord) {
+      return mismatchDescription.add('was not a LogRecord');
+    }
+    if (!_levelMatcher.matches(item.level, matchState)) {
+      return mismatchDescription
+          .add('level ')
+          .addDescriptionOf(item.level)
+          .add(' did not match ')
+          .addDescriptionOf(_levelMatcher);
+    }
+    if (!_messageMatcher.matches(item.message, matchState)) {
+      return mismatchDescription
+          .add('message ')
+          .addDescriptionOf(item.message)
+          .add(' did not match ')
+          .addDescriptionOf(_messageMatcher);
+    }
+    return mismatchDescription;
+  }
+}

From f78be46a3c04a4623036bba5d0cd17922960eaea Mon Sep 17 00:00:00 2001
From: Matan Lurey <matan@lurey.org>
Date: Tue, 1 Oct 2024 15:27:12 -0700
Subject: [PATCH 2/5] Configuration failure cases.

---
 .../lib/src/commands/run_command.dart         |  27 ++--
 tools/engine_tool/test/run_command_test.dart  | 139 +++++++++++++-----
 2 files changed, 120 insertions(+), 46 deletions(-)

diff --git a/tools/engine_tool/lib/src/commands/run_command.dart b/tools/engine_tool/lib/src/commands/run_command.dart
index 32de7ef18fed1..30063143f27f1 100644
--- a/tools/engine_tool/lib/src/commands/run_command.dart
+++ b/tools/engine_tool/lib/src/commands/run_command.dart
@@ -132,11 +132,11 @@ See `flutter run --help` for a listing
   Future<String> _selectTargetConfig() async {
     final configName = argResults![configFlag] as String;
     if (configName.isNotEmpty) {
-      return demangleConfigName(environment, configName);
+      return configName;
     }
     final target = await _runTarget;
     if (target == null) {
-      return demangleConfigName(environment, 'host_debug');
+      return 'host_debug';
     }
 
     final result = target.buildConfigFor(_getMode());
@@ -149,8 +149,8 @@ See `flutter run --help` for a listing
     if (!environment.processRunner.processManager.canRun('flutter')) {
       throw FatalError('Cannot find the "flutter" command in your PATH');
     }
-    final configName = await _selectTargetConfig();
 
+    final configName = await _selectTargetConfig();
     final targetBuild = _findTargetBuild(configName);
     if (targetBuild == null) {
       throw FatalError('Could not find build $configName');
@@ -161,22 +161,23 @@ See `flutter run --help` for a listing
       throw FatalError('Could not find host build for $configName');
     }
 
-    final bool useRbe = argResults![rbeFlag] as bool;
+    final useRbe = argResults!.flag(rbeFlag);
     if (useRbe && !environment.hasRbeConfigInTree()) {
-      environment.logger.error('RBE was requested but no RBE config was found');
-      return 1;
+      throw FatalError('RBE was requested but no RBE config was found');
     }
-    final List<String> extraGnArgs = <String>[
+
+    final extraGnArgs = [
       if (!useRbe) '--no-rbe',
     ];
-    final RunTarget? target = await _runTarget;
+    final target = await _runTarget;
     final buildTargetsForShell = target?.buildTargetsForShell ?? [];
 
-    final String dashJ = argResults![concurrencyFlag] as String;
-    final int? concurrency = int.tryParse(dashJ);
-    if (concurrency == null || concurrency < 0) {
-      environment.logger.error('-j must specify a positive integer.');
-      return 1;
+    final dashJ = argResults![concurrencyFlag] as String;
+    final concurrency = int.tryParse(dashJ);
+    if (concurrency == null || concurrency <= 0) {
+      throw FatalError(
+        '--$concurrencyFlag (-j) must specify a positive integer.',
+      );
     }
 
     // First build the host.
diff --git a/tools/engine_tool/test/run_command_test.dart b/tools/engine_tool/test/run_command_test.dart
index c580776efa97a..6e882f6acd04e 100644
--- a/tools/engine_tool/test/run_command_test.dart
+++ b/tools/engine_tool/test/run_command_test.dart
@@ -2,12 +2,10 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'dart:convert' show jsonDecode;
-import 'dart:ffi';
+import 'dart:ffi' show Abi;
 import 'dart:io' as io;
 
 import 'package:args/command_runner.dart';
-import 'package:engine_build_configs/engine_build_configs.dart';
 import 'package:engine_repo_tools/engine_repo_tools.dart';
 import 'package:engine_tool/src/commands/run_command.dart';
 import 'package:engine_tool/src/environment.dart';
@@ -19,33 +17,9 @@ import 'package:process_fakes/process_fakes.dart';
 import 'package:process_runner/process_runner.dart';
 import 'package:test/test.dart';
 
-import 'fixtures.dart' as fixtures;
+import 'src/test_build_configs.dart';
 
 void main() {
-  final linuxTestConfig = BuilderConfig.fromJson(
-    path: 'ci/builders/linux_test_config.json',
-    map: jsonDecode(fixtures.testConfig('Linux', Platform.linux))
-        as Map<String, Object?>,
-  );
-
-  final macTestConfig = BuilderConfig.fromJson(
-    path: 'ci/builders/mac_test_config.json',
-    map: jsonDecode(fixtures.testConfig('Mac-12', Platform.macOS))
-        as Map<String, Object?>,
-  );
-
-  final winTestConfig = BuilderConfig.fromJson(
-    path: 'ci/builders/win_test_config.json',
-    map: jsonDecode(fixtures.testConfig('Windows-11', Platform.windows))
-        as Map<String, Object?>,
-  );
-
-  final allTestConfigs = <String, BuilderConfig>{
-    'linux_test_config': linuxTestConfig,
-    'mac_test_config': macTestConfig,
-    'win_test_config': winTestConfig,
-  };
-
   late io.Directory tempRoot;
   late TestEngine testEngine;
 
@@ -69,7 +43,7 @@ void main() {
     );
 
     final testEnvironment = Environment(
-      abi: Abi.current(),
+      abi: Abi.macosArm64,
       engine: testEngine,
       logger: Logger.test((_) {}),
       platform: _fakePlatform(Platform.linux),
@@ -110,7 +84,7 @@ void main() {
     setUp(() {
       testLogs = [];
       testEnvironment = Environment(
-        abi: Abi.current(),
+        abi: Abi.linuxX64,
         engine: testEngine,
         logger: Logger.test(testLogs.add),
         platform: _fakePlatform(Platform.linux),
@@ -123,9 +97,19 @@ void main() {
     });
 
     test('fails if a target build could not be found', () async {
+      final builders = TestBuilderConfig();
+      builders.addBuild(
+        name: 'linux/android_debug_arm64',
+        dimension: TestDroneDimension.linux,
+      );
+
       final et = _engineTool(RunCommand(
         environment: testEnvironment,
-        configs: allTestConfigs,
+        configs: {
+          'linux_test_config': builders.buildConfig(
+            path: 'ci/builders/linux_test_config.json',
+          ),
+        },
         flutterTool: flutterTool,
       ));
 
@@ -142,9 +126,20 @@ void main() {
     });
 
     test('fails if a host build could not be found', () async {
+      final builders = TestBuilderConfig();
+      builders.addBuild(
+        name: 'linux/android_debug_arm64',
+        dimension: TestDroneDimension.linux,
+        targetDir: 'android_debug_arm64',
+      );
+
       final et = _engineTool(RunCommand(
         environment: testEnvironment,
-        configs: allTestConfigs,
+        configs: {
+          'linux_test_config': builders.buildConfig(
+            path: 'ci/builders/linux_test_config.json',
+          ),
+        },
         flutterTool: flutterTool,
       ));
 
@@ -154,11 +149,89 @@ void main() {
           isA<FatalError>().having(
             (a) => a.toString(),
             'toString()',
-            contains('Could not find build'),
+            contains('Could not find host build'),
           ),
         ),
       );
     });
+
+    test('fails if RBE was requested but no RBE config was found', () async {
+      final builders = TestBuilderConfig();
+      builders.addBuild(
+        name: 'linux/android_debug_arm64',
+        dimension: TestDroneDimension.linux,
+        targetDir: 'android_debug_arm64',
+      );
+      builders.addBuild(
+        name: 'linux/host_debug',
+        dimension: TestDroneDimension.linux,
+        targetDir: 'host_debug',
+      );
+
+      final et = _engineTool(RunCommand(
+        environment: testEnvironment,
+        configs: {
+          'linux_test_config': builders.buildConfig(
+            path: 'ci/builders/linux_test_config.json',
+          ),
+        },
+        flutterTool: flutterTool,
+      ));
+
+      expect(
+        () => et.run(['run', '--rbe', '--config=android_debug_arm64']),
+        throwsA(
+          isA<FatalError>().having(
+            (a) => a.toString(),
+            'toString()',
+            contains('RBE was requested but no RBE config was found'),
+          ),
+        ),
+      );
+    });
+
+    group('fails if -j is not a positive integer', () {
+      for (final arg in ['-1', '0', 'foo']) {
+        test('fails if -j is $arg', () async {
+          final builders = TestBuilderConfig();
+          builders.addBuild(
+            name: 'linux/android_debug_arm64',
+            dimension: TestDroneDimension.linux,
+            targetDir: 'android_debug_arm64',
+          );
+          builders.addBuild(
+            name: 'linux/host_debug',
+            dimension: TestDroneDimension.linux,
+            targetDir: 'host_debug',
+          );
+
+          final et = _engineTool(RunCommand(
+            environment: testEnvironment,
+            configs: {
+              'linux_test_config': builders.buildConfig(
+                path: 'ci/builders/linux_test_config.json',
+              ),
+            },
+            flutterTool: flutterTool,
+          ));
+
+          expect(
+            () => et.run([
+              'run',
+              '--config=android_debug_arm64',
+              '--concurrency=$arg',
+            ]),
+            throwsA(
+              isA<FatalError>().having(
+                (a) => a.toString(),
+                'toString()',
+                contains('concurrency (-j) must specify a positive integer'),
+              ),
+            ),
+          );
+        });
+      }
+    });
   });
 }
 

From d9b5162b136f7fab54216bdcd258d8ded50a2fc1 Mon Sep 17 00:00:00 2001
From: Matan Lurey <matan@lurey.org>
Date: Wed, 2 Oct 2024 12:17:13 -0700
Subject: [PATCH 3/5] Finish run tests.

---
 .../lib/src/commands/run_command.dart         |   6 +-
 tools/engine_tool/test/run_command_test.dart  | 347 +++++++++++++++++-
 2 files changed, 349 insertions(+), 4 deletions(-)

diff --git a/tools/engine_tool/lib/src/commands/run_command.dart b/tools/engine_tool/lib/src/commands/run_command.dart
index 30063143f27f1..798d81e55eb42 100644
--- a/tools/engine_tool/lib/src/commands/run_command.dart
+++ b/tools/engine_tool/lib/src/commands/run_command.dart
@@ -174,7 +174,7 @@ See `flutter run --help` for a listing
 
     final dashJ = argResults![concurrencyFlag] as String;
     final concurrency = int.tryParse(dashJ);
-    if (concurrency == null || concurrency <= 0) {
+    if (concurrency == null || concurrency < 0) {
       throw FatalError(
         '--$concurrencyFlag (-j) must specify a positive integer.',
       );
@@ -189,7 +189,7 @@ See `flutter run --help` for a listing
       enableRbe: useRbe,
     );
     if (r != 0) {
-      return r;
+      throw FatalError('Failed to build host (${hostBuild.name})');
     }
 
     // Now build the target if it isn't the same.
@@ -203,7 +203,7 @@ See `flutter run --help` for a listing
         targets: buildTargetsForShell,
       );
       if (r != 0) {
-        return r;
+        throw FatalError('Failed to build target (${targetBuild.name})');
       }
     }
 
diff --git a/tools/engine_tool/test/run_command_test.dart b/tools/engine_tool/test/run_command_test.dart
index 6e882f6acd04e..0d04f012bfab6 100644
--- a/tools/engine_tool/test/run_command_test.dart
+++ b/tools/engine_tool/test/run_command_test.dart
@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:convert';
 import 'dart:ffi' show Abi;
 import 'dart:io' as io;
 
@@ -12,6 +13,7 @@ import 'package:engine_tool/src/environment.dart';
 import 'package:engine_tool/src/flutter_tool_interop/device.dart';
 import 'package:engine_tool/src/flutter_tool_interop/flutter_tool.dart';
 import 'package:engine_tool/src/logger.dart';
+import 'package:path/path.dart' as p;
 import 'package:platform/platform.dart';
 import 'package:process_fakes/process_fakes.dart';
 import 'package:process_runner/process_runner.dart';
@@ -56,6 +58,7 @@ void main() {
     final et = _engineTool(
       RunCommand(
         environment: testEnvironment,
+        // Intentionally left blank, none of these builds make it far enough.
         configs: {},
       ),
     );
@@ -191,7 +194,7 @@ void main() {
     });
 
     group('fails if -j is not a positive integer', () {
-      for (final arg in ['-1', '0', 'foo']) {
+      for (final arg in ['-1', 'foo']) {
         test('fails if -j is $arg', () async {
           final builders = TestBuilderConfig();
           builders.addBuild(
@@ -233,6 +236,348 @@ void main() {
       }
     });
   });
+
+  group('builds and executes `flutter run`', () {
+    late CommandRunner<int> et;
+    late io.Directory rbeDir;
+
+    var commandsRun = <List<String>>[];
+    var testLogs = <LogRecord>[];
+    var attachedDevices = <Device>[];
+    var interceptCommands = <(String, FakeProcess? Function(List<String>))>[];
+
+    setUp(() {
+      // Builder configuration doesn't change for these tests.
+      final builders = TestBuilderConfig();
+      builders.addBuild(
+        name: 'linux/android_debug_arm64',
+        dimension: TestDroneDimension.linux,
+        targetDir: 'android_debug_arm64',
+        enableRbe: true,
+      );
+      builders.addBuild(
+        name: 'linux/host_debug',
+        dimension: TestDroneDimension.linux,
+        targetDir: 'host_debug',
+        enableRbe: true,
+      );
+
+      // Be very permissive on process execution, and check usage below instead.
+      final permissiveProcessManager = FakeProcessManager(
+        canRun: (_, {workingDirectory}) => true,
+        onRun: (command) {
+          commandsRun.add(command);
+          return io.ProcessResult(81, 0, '', '');
+        },
+        onStart: (command) {
+          commandsRun.add(command);
+          for (final entry in interceptCommands) {
+            if (command.first.endsWith(entry.$1)) {
+              final result = entry.$2(command);
+              if (result != null) {
+                return result;
+              }
+            }
+          }
+          switch (command) {
+            case ['flutter', 'devices', '--machine', ..._]:
+              return FakeProcess(stdout: jsonEncode(attachedDevices));
+            default:
+              return FakeProcess();
+          }
+        },
+      );
+
+      // Create an RBE directory by default.
+      rbeDir = io.Directory(p.join(
+        testEngine.srcDir.path,
+        'flutter',
+        'build',
+        'rbe',
+      ));
+      rbeDir.createSync(recursive: true);
+
+      // Set up the environment for the test.
+      final testEnvironment = Environment(
+        abi: Abi.linuxX64,
+        engine: testEngine,
+        logger: Logger.test((log) {
+          testLogs.add(log);
+        }),
+        platform: _fakePlatform(Platform.linux),
+        processRunner: ProcessRunner(
+          defaultWorkingDirectory: tempRoot,
+          processManager: permissiveProcessManager,
+        ),
+      );
+
+      // Set up the Flutter tool for the test.
+      et = _engineTool(RunCommand(
+        environment: testEnvironment,
+        configs: {
+          'linux_test_config': builders.buildConfig(
+            path: 'ci/builders/linux_test_config.json',
+          ),
+        },
+      ));
+
+      // Reset logs.
+      commandsRun = [];
+      attachedDevices = [];
+      testLogs = [];
+      interceptCommands = [];
+    });
+
+    tearDown(() {
+      printOnFailure('Commands run:\n${commandsRun.map((c) => c.join('\n'))}');
+      printOnFailure('Logs:\n${testLogs.map((l) => l.message).join('\n')}');
+    });
+
+    test('build includes RBE flags when enabled implicitly', () async {
+      await et.run([
+        'run',
+        '--config=android_debug_arm64',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          // ./tools/gn --rbe
+          containsAllInOrder([
+            endsWith('tools/gn'),
+            contains('--rbe'),
+          ]),
+
+          // ./reclient/bootstrap
+          containsAllInOrder([
+            endsWith('reclient/bootstrap'),
+          ]),
+        ]),
+      );
+    });
+
+    test('build excludes RBE flags when disabled', () async {
+      await et.run([
+        'run',
+        '--config=android_debug_arm64',
+        '--no-rbe',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          // ./tools/gn --no-rbe
+          containsAllInOrder([
+            endsWith('tools/gn'),
+            contains('--no-rbe'),
+          ]),
+
+          // ./reclient/bootstrap
+          isNot(containsAllInOrder([
+            endsWith('reclient/bootstrap'),
+          ])),
+        ]),
+      );
+    });
+
+    test('picks a default concurrency for RBE builds', () async {
+      await et.run([
+        'run',
+        '--config=android_debug_arm64',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          // ninja -C out/android_debug_arm64 -j 1000 (or whatever is picked)
+          containsAllInOrder([
+            endsWith('ninja/ninja'),
+            contains('-j'),
+            isA<String>().having(int.tryParse, 'concurrency', greaterThan(100)),
+          ]),
+        ]),
+      );
+    });
+
+    test('does not define a default concurrency for non-RBE builds', () async {
+      await et.run([
+        'run',
+        '--no-rbe',
+        '--config=android_debug_arm64',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          containsAllInOrder([
+            endsWith('ninja/ninja'),
+            isNot(contains('-j')),
+          ]),
+        ]),
+      );
+    });
+
+    test('define a user-specified concurrency for non-RBE builds', () async {
+      await et.run([
+        'run',
+        '--concurrency=42',
+        '--no-rbe',
+        '--config=android_debug_arm64',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          containsAllInOrder([
+            endsWith('ninja/ninja'),
+            contains('-j'),
+            '42',
+          ]),
+        ]),
+      );
+    });
+
+    test('handles host build failures', () async {
+      interceptCommands.add((
+        'ninja',
+        (command) {
+          print(command);
+          if (command.any((c) => c.contains('host_debug'))) {
+            return FakeProcess(exitCode: 1);
+          }
+          return null;
+        },
+      ));
+
+      expect(
+        () => et.run([
+          'run',
+          '--config=android_debug_arm64',
+        ]),
+        throwsA(
+          isA<FatalError>().having(
+            (a) => a.toString(),
+            'toString()',
+            contains('Failed to build host'),
+          ),
+        ),
+      );
+    });
+
+    test('handles target build failures', () async {
+      interceptCommands.add((
+        'ninja',
+        (command) {
+          if (command.any((c) => c.contains('android_debug_arm64'))) {
+            return FakeProcess(exitCode: 1);
+          }
+          return null;
+        },
+      ));
+
+      expect(
+        () => et.run([
+          'run',
+          '--config=android_debug_arm64',
+        ]),
+        throwsA(
+          isA<FatalError>().having(
+            (a) => a.toString(),
+            'toString()',
+            contains('Failed to build target'),
+          ),
+        ),
+      );
+    });
+
+    test('builds only once if the target and host are the same', () async {
+      await et.run([
+        'run',
+        '--config=host_debug',
+      ]);
+
+      expect(
+        commandsRun,
+        containsOnce(
+          containsAllInOrder([
+            endsWith('ninja'),
+          ]),
+        ),
+      );
+    });
+
+    test('builds both the target and host if they are different', () async {
+      await et.run([
+        'run',
+        '--config=android_debug_arm64',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          containsAllInOrder([
+            endsWith('ninja'),
+            contains('host_debug'),
+          ]),
+          containsAllInOrder([
+            endsWith('ninja'),
+            contains('android_debug_arm64'),
+          ]),
+        ]),
+      );
+    });
+
+    test('delegates to `flutter run` with --local-engine flags', () async {
+      await et.run([
+        'run',
+        '--config=android_debug_arm64',
+      ]);
+
+      expect(
+        commandsRun,
+        containsAllInOrder([
+          containsAllInOrder([
+            endsWith('flutter'),
+            contains('run'),
+            '--local-engine-src-path',
+            testEngine.srcDir.path,
+            '--local-engine',
+            'android_debug_arm64',
+            '--local-engine-host',
+            'host_debug',
+          ]),
+        ]),
+      );
+    });
+
+    group('delegates to `flutter run` in mode', () {
+      for (final mode in const ['debug', 'profile', 'release']) {
+        test('$mode mode', () async {
+          await et.run([
+            'run',
+            '--config=android_debug_arm64',
+            '--',
+            '--$mode',
+          ]);
+
+          expect(
+            commandsRun,
+            containsAllInOrder([
+              containsAllInOrder([
+                endsWith('flutter'),
+                contains('run'),
+                contains('--$mode'),
+              ]),
+            ]),
+          );
+        });
+      }
+    });
+  });
+
+  // FIXME: Add positive tests.
+  // ^^^ Both sets, calls flutter run as expected n stuff.
+  // ... and check debug/profile/release
 }
 
 CommandRunner<int> _engineTool(RunCommand runCommand) {

From fa1c5d16d8f965e4cb5f5a4a5097da7981d683ee Mon Sep 17 00:00:00 2001
From: Matan Lurey <matan@lurey.org>
Date: Thu, 3 Oct 2024 11:06:29 -0700
Subject: [PATCH 4/5] ++

---
 tools/engine_tool/test/run_command_test.dart | 29 --------------------
 1 file changed, 29 deletions(-)

diff --git a/tools/engine_tool/test/run_command_test.dart b/tools/engine_tool/test/run_command_test.dart
index 0d04f012bfab6..99ad33b5a415e 100644
--- a/tools/engine_tool/test/run_command_test.dart
+++ b/tools/engine_tool/test/run_command_test.dart
@@ -99,35 +99,6 @@ void main() {
       flutterTool = _FakeFlutterTool();
     });
 
-    test('fails if a target build could not be found', () async {
-      final builders = TestBuilderConfig();
-      builders.addBuild(
-        name: 'linux/android_debug_arm64',
-        dimension: TestDroneDimension.linux,
-      );
-
-      final et = _engineTool(RunCommand(
-        environment: testEnvironment,
-        configs: {
-          'linux_test_config': builders.buildConfig(
-            path: 'ci/builders/linux_test_config.json',
-          ),
-        },
-        flutterTool: flutterTool,
-      ));
-
-      expect(
-        () => et.run(['run', '--config=android_debug_arm64']),
-        throwsA(
-          isA<FatalError>().having(
-            (a) => a.toString(),
-            'toString()',
-            contains('Could not find build'),
-          ),
-        ),
-      );
-    });
-
     test('fails if a host build could not be found', () async {
       final builders = TestBuilderConfig();
       builders.addBuild(

From 6a355604cbb88c9a0b34cc8214cf2ed5f687c557 Mon Sep 17 00:00:00 2001
From: Matan Lurey <matan@lurey.org>
Date: Thu, 3 Oct 2024 11:12:43 -0700
Subject: [PATCH 5/5] ++

---
 tools/engine_tool/lib/src/commands/run_command.dart | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/tools/engine_tool/lib/src/commands/run_command.dart b/tools/engine_tool/lib/src/commands/run_command.dart
index 798d81e55eb42..2460a19db5c91 100644
--- a/tools/engine_tool/lib/src/commands/run_command.dart
+++ b/tools/engine_tool/lib/src/commands/run_command.dart
@@ -172,8 +172,7 @@ See `flutter run --help` for a listing
     final target = await _runTarget;
     final buildTargetsForShell = target?.buildTargetsForShell ?? [];
 
-    final dashJ = argResults![concurrencyFlag] as String;
-    final concurrency = int.tryParse(dashJ);
+    final concurrency = int.tryParse(argResults![concurrencyFlag] as String);
     if (concurrency == null || concurrency < 0) {
       throw FatalError(
         '--$concurrencyFlag (-j) must specify a positive integer.',