Add a better error message when flutter drive --target is used incorrectly. (#162023)

Closes https://github.com/flutter/flutter/issues/62626.

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

@@ -284,6 +284,15 @@ class DriveCommand extends RunCommandBase {
       throwToolExit(null);
     }
     if (await _fileSystem.type(testFile) != FileSystemEntityType.file) {
+      // A very common source of error is holding "flutter drive" wrong,
+      // and providing the "test_driver/foo_test.dart" as the target, when
+      // the intention was to provide "lib/foo.dart".
+      if (_fileSystem.path.isWithin('test_driver', targetFile)) {
+        _logger.printError(
+          'The file path passed to --target should be an app entrypoint that '
+          'contains a "main()". Did you mean "flutter drive --driver $targetFile"?',
+        );
+      }
       throwToolExit('Test file not found: $testFile');
     }
     final Device? device = await targetedDevice;

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

@@ -53,6 +53,94 @@ void main() {
     Cache.enableLocking();
   });
 
+  testUsingContext(
+    'fails if the specified --target is not found',
+    () async {
+      final DriveCommand command = DriveCommand(
+        fileSystem: fileSystem,
+        logger: logger,
+        platform: platform,
+        signals: signals,
+      );
+      fileSystem.file('lib/main.dart').createSync(recursive: true);
+      fileSystem.file('test_driver/main_test.dart').createSync(recursive: true);
+      fileSystem.file('pubspec.yaml').createSync();
+
+      await expectLater(
+        () => createTestCommandRunner(
+          command,
+        ).run(<String>['drive', '--no-pub', '--target', 'lib/app.dart']),
+        throwsToolExit(message: 'Target file "lib/app.dart" not found'),
+      );
+
+      expect(logger.errorText, isEmpty);
+      expect(logger.statusText, isEmpty);
+    },
+    overrides: <Type, Generator>{
+      FileSystem: () => fileSystem,
+      ProcessManager: () => FakeProcessManager.empty(),
+    },
+  );
+
+  testUsingContext(
+    'fails if the default --target is not found',
+    () async {
+      final DriveCommand command = DriveCommand(
+        fileSystem: fileSystem,
+        logger: logger,
+        platform: platform,
+        signals: signals,
+      );
+      fileSystem.file('lib/app.dart').createSync(recursive: true);
+      fileSystem.file('test_driver/app_test.dart').createSync(recursive: true);
+      fileSystem.file('pubspec.yaml').createSync();
+
+      await expectLater(
+        () => createTestCommandRunner(command).run(<String>['drive', '--no-pub']),
+        throwsToolExit(message: 'Target file "lib/main.dart" not found'),
+      );
+
+      expect(logger.errorText, isEmpty);
+      expect(logger.statusText, isEmpty);
+    },
+    overrides: <Type, Generator>{
+      FileSystem: () => fileSystem,
+      ProcessManager: () => FakeProcessManager.empty(),
+    },
+  );
+
+  testUsingContext(
+    'fails with an informative error message if --target looks like --driver',
+    () async {
+      final DriveCommand command = DriveCommand(
+        fileSystem: fileSystem,
+        logger: logger,
+        platform: platform,
+        signals: signals,
+      );
+      fileSystem.file('lib/main.dart').createSync(recursive: true);
+      fileSystem.file('test_driver/main_test.dart').createSync(recursive: true);
+      fileSystem.file('pubspec.yaml').createSync();
+
+      await expectLater(
+        () => createTestCommandRunner(
+          command,
+        ).run(<String>['drive', '--no-pub', '--target', 'test_driver/main_test.dart']),
+        throwsToolExit(message: 'Test file not found: /test_driver/main_test_test.dart'),
+      );
+
+      expect(
+        logger.errorText,
+        contains('The file path passed to --target should be an app entrypoint'),
+      );
+      expect(logger.statusText, isEmpty);
+    },
+    overrides: <Type, Generator>{
+      FileSystem: () => fileSystem,
+      ProcessManager: () => FakeProcessManager.empty(),
+    },
+  );
+
   testUsingContext(
     'warns if screenshot is not supported but continues test',
     () async {