feat(test): add --device flag to target a specific Android device by serial

internal/android/android.go

@@ -17,17 +17,22 @@ import (
 
 // EnsureDevice makes sure an Android device is ready for adb commands.
 // Resolution order:
-//   - if an adb device is already online, use it;
+//   - if serial is set, require that exact device to be online;
+//   - else if an adb device is already online, use it;
 //   - else if avdName is set, validate and boot it;
 //   - else if exactly one AVD exists locally, boot it;
 //   - else fail with a helpful message listing the available AVDs.
-func EnsureDevice(ctx context.Context, avdName string, stdout io.Writer) error {
+func EnsureDevice(ctx context.Context, serial, avdName string, stdout io.Writer) error {
 	devices, err := listAdbDevices(ctx)
 	if err != nil {
 		return fmt.Errorf("list adb devices: %w", err)
 	}
-	if len(devices) > 0 {
-		fmt.Fprintf(stdout, "using connected device: %s\n", devices[0])
+	chosen, found, err := pickDevice(serial, devices)
+	if err != nil {
+		return err
+	}
+	if found {
+		fmt.Fprintf(stdout, "using connected device: %s\n", chosen)
 		return nil
 	}
 	avds, err := listAVDs(ctx)
@@ -191,6 +196,22 @@ func parseAVDList(output string) []string {
 	return avds
 }
 
+// pickDevice resolves which connected device to drive. A requested serial must
+// be online; with no request the first connected device is used, else found is
+// false so the caller falls back to booting an AVD.
+func pickDevice(requested string, connected []string) (serial string, found bool, err error) {
+	if requested != "" {
+		if !slices.Contains(connected, requested) {
+			return "", false, fmt.Errorf("device %q is not connected (online devices: %s)", requested, strings.Join(connected, ", "))
+		}
+		return requested, true, nil
+	}
+	if len(connected) > 0 {
+		return connected[0], true, nil
+	}
+	return "", false, nil
+}
+
 func pickAVD(requested string, available []string) (string, error) {
 	if requested != "" {
 		if !slices.Contains(available, requested) {

internal/android/android_test.go

@@ -28,6 +28,37 @@ func TestParseAdbDevices_Empty(t *testing.T) {
 	}
 }
 
+func TestPickDevice_RequestedOnline(t *testing.T) {
+	serial, found, err := pickDevice("physical-abc", []string{"emulator-5554", "physical-abc"})
+	if err != nil || !found || serial != "physical-abc" {
+		t.Fatalf("got (%q, %v, %v), want (physical-abc, true, nil)", serial, found, err)
+	}
+}
+
+func TestPickDevice_RequestedNotConnected(t *testing.T) {
+	_, found, err := pickDevice("physical-abc", []string{"emulator-5554"})
+	if err == nil {
+		t.Fatal("expected error for a serial that is not connected")
+	}
+	if found {
+		t.Fatal("found must be false when the requested device is absent")
+	}
+}
+
+func TestPickDevice_NoRequestUsesFirst(t *testing.T) {
+	serial, found, err := pickDevice("", []string{"emulator-5554", "physical-abc"})
+	if err != nil || !found || serial != "emulator-5554" {
+		t.Fatalf("got (%q, %v, %v), want (emulator-5554, true, nil)", serial, found, err)
+	}
+}
+
+func TestPickDevice_NoneConnectedFallsBackToAVD(t *testing.T) {
+	serial, found, err := pickDevice("", nil)
+	if err != nil || found || serial != "" {
+		t.Fatalf("got (%q, %v, %v), want (\"\", false, nil)", serial, found, err)
+	}
+}
+
 func TestParseAVDList_DropsInfoLines(t *testing.T) {
 	output := `INFO    | Storing crashdata in: /tmp/x
 Medium_Phone_API_36.0