@react-native-harness/platform-android 1.1.0-rc.4 → 1.2.0-rc.1

package/src/__tests__/adb.test.ts

@@ -12,11 +12,13 @@ import {
   hasAvd,
   installApp,
   startEmulator,
+  uninstallApp,
   waitForBoot,
   waitForEmulatorDisconnect,
 } from '../adb.js';
 import * as tools from '@react-native-harness/tools';
 import * as environment from '../environment.js';
+import * as avdConfig from '../avd-config.js';
 
 const createAbortError = () =>
   new DOMException('The operation was aborted', 'AbortError');
@@ -48,7 +50,7 @@ describe('getStartAppArgs', () => {
           user_id: 42,
           mode: 'debug',
         },
-      })
+      }),
     ).toEqual([
       'shell',
       'am',
@@ -77,7 +79,7 @@ describe('getStartAppArgs', () => {
         extras: {
           count: Number.MAX_SAFE_INTEGER + 1,
         },
-      })
+      }),
     ).toThrow('must be a safe integer');
   });
 
@@ -88,7 +90,7 @@ describe('getStartAppArgs', () => {
     } as Awaited<ReturnType<typeof tools.spawn>>);
 
     await expect(getAppUid('emulator-5554', 'com.example.app')).resolves.toBe(
-      10234
+      10234,
     );
 
     expect(spawnSpy).toHaveBeenCalledWith(expect.stringMatching(/adb$/), [
@@ -108,7 +110,7 @@ describe('getStartAppArgs', () => {
     } as Awaited<ReturnType<typeof tools.spawn>>);
 
     await expect(getLogcatTimestamp('emulator-5554')).resolves.toBe(
-      '03-12 11:35:08.000'
+      '03-12 11:35:08.000',
     );
 
     expect(spawnSpy).toHaveBeenCalledWith(expect.stringMatching(/adb$/), [
@@ -145,15 +147,35 @@ describe('getStartAppArgs', () => {
     ]);
   });
 
+  it('uninstalls the app via adb', async () => {
+    const spawnSpy = vi
+      .spyOn(tools, 'spawn')
+      .mockResolvedValueOnce({} as Awaited<ReturnType<typeof tools.spawn>>);
+
+    await uninstallApp('emulator-5554', 'com.example.app');
+
+    expect(spawnSpy).toHaveBeenCalledWith(expect.stringMatching(/adb$/), [
+      '-s',
+      'emulator-5554',
+      'uninstall',
+      'com.example.app',
+    ]);
+  });
+
   it('creates an AVD and appends config overrides', async () => {
+    vi.spyOn(avdConfig, 'readAvdConfig').mockResolvedValue({});
     const spawnSpy = vi
       .spyOn(tools, 'spawn')
-      .mockResolvedValue({} as Awaited<ReturnType<typeof tools.spawn>>);
+      .mockResolvedValue({} as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout:
+          'id: 0 or "pixel_8"\n    Name: Pixel 8\nid: 1 or "pixel_6"\n    Name: Pixel 6\n',
+      } as Awaited<ReturnType<typeof tools.spawn>>);
     const verifyAndroidEmulatorSdk = vi
       .spyOn(environment, 'ensureAndroidSdkPackages')
       .mockResolvedValue('/tmp/android-sdk');
     vi.spyOn(environment, 'getHostAndroidSystemImageArch').mockReturnValue(
-      'x86_64'
+      'x86_64',
     );
 
     await createAvd({
@@ -170,29 +192,128 @@ describe('getStartAppArgs', () => {
       'platforms;android-35',
       'system-images;android-35;default;x86_64',
     ]);
-    expect(spawnSpy).toHaveBeenNthCalledWith(1, 'bash', [
+    expect(spawnSpy).toHaveBeenNthCalledWith(
+      1,
+      expect.stringMatching(/avdmanager$/),
+      ['list', 'device'],
+    );
+    expect(spawnSpy).toHaveBeenNthCalledWith(2, 'bash', [
       '-lc',
       expect.stringContaining(
-        'create avd --force --name "Pixel_8_API_35" --package "system-images;android-35;default;x86_64" --device "pixel_8"'
+        'create avd --force --name "Pixel_8_API_35" --package "system-images;android-35;default;x86_64" --device "pixel_8" -p ',
       ),
     ]);
-    expect(spawnSpy).toHaveBeenNthCalledWith(2, 'bash', [
+    expect(spawnSpy).toHaveBeenNthCalledWith(3, 'bash', [
+      '-lc',
+      expect.stringContaining(`'avd.ini.encoding=UTF-8' 'path=`),
+    ]);
+    expect(spawnSpy).toHaveBeenNthCalledWith(4, 'bash', [
       '-lc',
       expect.stringContaining(
-        `'disk.dataPartition.size=1G' 'vm.heapSize=1G' >> `
+        `'disk.dataPartition.size=1G' 'vm.heapSize=1G' >> `,
       ),
     ]);
   });
 
-  it('creates an AVD with arm64 system image packages on arm64 hosts', async () => {
-    vi.spyOn(tools, 'spawn').mockResolvedValue(
-      {} as Awaited<ReturnType<typeof tools.spawn>>
+  it('recreates the companion ini file when avdmanager leaves it missing', async () => {
+    vi.spyOn(avdConfig, 'readAvdConfig').mockResolvedValue({});
+    const spawnSpy = vi
+      .spyOn(tools, 'spawn')
+      .mockResolvedValue({} as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: 'id: 0 or "pixel_6"\n    Name: Pixel 6\n',
+      } as Awaited<ReturnType<typeof tools.spawn>>);
+    vi.spyOn(environment, 'ensureAndroidSdkPackages').mockResolvedValue(
+      '/tmp/android-sdk',
+    );
+    vi.spyOn(environment, 'getHostAndroidSystemImageArch').mockReturnValue(
+      'x86_64',
+    );
+
+    await createAvd({
+      name: 'Pixel_6_API_35',
+      apiLevel: 35,
+      profile: 'pixel_6',
+      diskSize: '1G',
+      heapSize: '1G',
+    });
+
+    expect(spawnSpy).toHaveBeenNthCalledWith(3, 'bash', [
+      '-lc',
+      expect.stringContaining(`'avd.ini.encoding=UTF-8' 'path=`),
+    ]);
+    expect(spawnSpy).toHaveBeenNthCalledWith(4, 'bash', [
+      '-lc',
+      expect.stringContaining(
+        `'disk.dataPartition.size=1G' 'vm.heapSize=1G' >> `,
+      ),
+    ]);
+  });
+
+  it('throws an actionable error when the requested AVD profile is unavailable', async () => {
+    vi.spyOn(tools, 'spawn').mockResolvedValueOnce({
+      stdout:
+        'id: 0 or "pixel_8"\n    Name: Pixel 8\nid: 1 or "pixel_6"\n    Name: Pixel 6\n',
+    } as Awaited<ReturnType<typeof tools.spawn>>);
+    vi.spyOn(environment, 'ensureAndroidSdkPackages').mockResolvedValue(
+      '/tmp/android-sdk',
+    );
+    vi.spyOn(environment, 'getHostAndroidSystemImageArch').mockReturnValue(
+      'x86_64',
+    );
+
+    await expect(
+      createAvd({
+        name: 'Pixel_8_Pro_API_35',
+        apiLevel: 35,
+        profile: 'pixel_8_pro',
+        diskSize: '1G',
+        heapSize: '1G',
+      }),
+    ).rejects.toThrow(
+      'Android AVD profile "pixel_8_pro" is not available on this machine. Available profiles: pixel_8, pixel_6',
+    );
+  });
+
+  it('throws a clear error when avdmanager does not create config.ini', async () => {
+    vi.spyOn(avdConfig, 'readAvdConfig').mockResolvedValue(null);
+    vi.spyOn(tools, 'spawn')
+      .mockResolvedValue({} as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: 'id: 0 or "pixel_6"\n    Name: Pixel 6\n',
+      } as Awaited<ReturnType<typeof tools.spawn>>);
+    vi.spyOn(environment, 'ensureAndroidSdkPackages').mockResolvedValue(
+      '/tmp/android-sdk',
+    );
+    vi.spyOn(environment, 'getHostAndroidSystemImageArch').mockReturnValue(
+      'x86_64',
+    );
+
+    await expect(
+      createAvd({
+        name: 'Pixel_6_API_35',
+        apiLevel: 35,
+        profile: 'pixel_6',
+        diskSize: '1G',
+        heapSize: '1G',
+      }),
+    ).rejects.toThrow(
+      'Android AVD "Pixel_6_API_35" was created, but config.ini was not found at ',
     );
+  });
+
+  it('creates an AVD with arm64 system image packages on arm64 hosts', async () => {
+    vi.spyOn(avdConfig, 'readAvdConfig').mockResolvedValue({});
+    vi.spyOn(tools, 'spawn')
+      .mockResolvedValue({} as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: 'id: 0 or "pixel_8"\n    Name: Pixel 8\n',
+      } as Awaited<ReturnType<typeof tools.spawn>>);
     const ensureAndroidSdkPackages = vi
       .spyOn(environment, 'ensureAndroidSdkPackages')
       .mockResolvedValue('/tmp/android-sdk');
     vi.spyOn(environment, 'getHostAndroidSystemImageArch').mockReturnValue(
-      'arm64-v8a'
+      'arm64-v8a',
     );
 
     await createAvd({
@@ -241,7 +362,7 @@ describe('getStartAppArgs', () => {
     child.emit('close', 1, null);
 
     await expect(startPromise).rejects.toThrow(
-      'Unknown AVD name [Pixel_8_API_35]'
+      'Unknown AVD name [Pixel_8_API_35]',
     );
   });
 
@@ -271,7 +392,7 @@ describe('getStartAppArgs', () => {
     child.emit('close', 1, null);
 
     await expect(startPromise).rejects.toThrow(
-      'emulator: panic: broken config'
+      'emulator: panic: broken config',
     );
   });
 
@@ -291,7 +412,7 @@ describe('getStartAppArgs', () => {
     vi.spyOn(emulatorProcess, 'startDetachedProcess').mockReturnValue(
       child as unknown as ReturnType<
         typeof emulatorProcess.startDetachedProcess
-      >
+      >,
     );
 
     const startPromise = startEmulator('Pixel_8_API_35');
@@ -317,7 +438,7 @@ describe('getStartAppArgs', () => {
       .mockReturnValue(
         child as unknown as ReturnType<
           typeof emulatorProcess.startDetachedProcess
-        >
+        >,
       );
 
     const startPromise = startEmulator('Pixel_8_API_35');
@@ -326,7 +447,7 @@ describe('getStartAppArgs', () => {
 
     expect(startDetachedProcess).toHaveBeenCalledWith(
       expect.stringMatching(/emulator$/),
-      expect.arrayContaining(['-no-snapshot-load', '-no-snapshot-save'])
+      expect.arrayContaining(['-no-snapshot-load', '-no-snapshot-save']),
     );
   });
 
@@ -345,22 +466,22 @@ describe('getStartAppArgs', () => {
       .mockReturnValue(
         child as unknown as ReturnType<
           typeof emulatorProcess.startDetachedProcess
-        >
+        >,
       );
 
     const startPromise = startEmulator(
       'Pixel_8_API_35',
-      'clean-snapshot-generation'
+      'clean-snapshot-generation',
     );
     await vi.runAllTimersAsync();
     await startPromise;
 
     expect(startDetachedProcess).toHaveBeenCalledWith(
       expect.stringMatching(/emulator$/),
-      expect.arrayContaining(['-no-snapshot-load'])
+      expect.arrayContaining(['-no-snapshot-load']),
     );
     expect(startDetachedProcess.mock.calls[0]?.[1]).not.toContain(
-      '-no-snapshot-save'
+      '-no-snapshot-save',
     );
   });
 
@@ -379,7 +500,7 @@ describe('getStartAppArgs', () => {
       .mockReturnValue(
         child as unknown as ReturnType<
           typeof emulatorProcess.startDetachedProcess
-        >
+        >,
       );
 
     const startPromise = startEmulator('Pixel_8_API_35', 'snapshot-reuse');
@@ -388,10 +509,10 @@ describe('getStartAppArgs', () => {
 
     expect(startDetachedProcess).toHaveBeenCalledWith(
       expect.stringMatching(/emulator$/),
-      expect.arrayContaining(['-no-snapshot-save'])
+      expect.arrayContaining(['-no-snapshot-save']),
     );
     expect(startDetachedProcess.mock.calls[0]?.[1]).not.toContain(
-      '-no-snapshot-load'
+      '-no-snapshot-load',
     );
   });
 
@@ -459,7 +580,7 @@ describe('getStartAppArgs', () => {
 
     const waitPromise = waitForBoot(
       'Pixel_8_API_35',
-      new AbortController().signal
+      new AbortController().signal,
     );
 
     await vi.advanceTimersByTimeAsync(1000);
@@ -482,7 +603,7 @@ describe('getStartAppArgs', () => {
 
     const waitPromise = waitForEmulatorDisconnect(
       'emulator-5554',
-      new AbortController().signal
+      new AbortController().signal,
     );
 
     await vi.advanceTimersByTimeAsync(1000);
@@ -490,4 +611,90 @@ describe('getStartAppArgs', () => {
     await expect(waitPromise).resolves.toBeUndefined();
     expect(spawnSpy).toHaveBeenCalledTimes(2);
   });
+
+  it('grants requested dangerous permissions to an app', async () => {
+    const { grantPermissions } = await import('../adb.js');
+    const spawnSpy = vi
+      .spyOn(tools, 'spawn')
+      .mockResolvedValueOnce({
+        stdout: 'package:com.example.app\n',
+      } as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: `requested permissions:\n  android.permission.CAMERA\n  android.permission.INTERNET\n  android.permission.ACCESS_FINE_LOCATION\ninstall permissions:\n`,
+      } as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: `Dangerous Permissions:\n  permission:android.permission.CAMERA\n  permission:android.permission.ACCESS_FINE_LOCATION\n`,
+      } as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValue({
+        stdout: '',
+      } as Awaited<ReturnType<typeof tools.spawn>>);
+
+    await grantPermissions('emulator-5554', 'com.example.app');
+
+    expect(spawnSpy).toHaveBeenCalledTimes(5);
+    expect(spawnSpy).toHaveBeenNthCalledWith(1, expect.any(String), [
+      '-s',
+      'emulator-5554',
+      'shell',
+      'pm',
+      'list',
+      'packages',
+      'com.example.app',
+    ]);
+    expect(spawnSpy).toHaveBeenNthCalledWith(2, expect.any(String), [
+      '-s',
+      'emulator-5554',
+      'shell',
+      'dumpsys',
+      'package',
+      'com.example.app',
+    ]);
+    expect(spawnSpy).toHaveBeenNthCalledWith(3, expect.any(String), [
+      '-s',
+      'emulator-5554',
+      'shell',
+      'pm',
+      'list',
+      'permissions',
+      '-g',
+      '-d',
+    ]);
+    expect(spawnSpy).toHaveBeenNthCalledWith(4, expect.any(String), [
+      '-s',
+      'emulator-5554',
+      'shell',
+      'pm',
+      'grant',
+      'com.example.app',
+      'android.permission.CAMERA',
+    ]);
+    expect(spawnSpy).toHaveBeenNthCalledWith(5, expect.any(String), [
+      '-s',
+      'emulator-5554',
+      'shell',
+      'pm',
+      'grant',
+      'com.example.app',
+      'android.permission.ACCESS_FINE_LOCATION',
+    ]);
+  });
+
+  it('does nothing when the app has no grantable dangerous permissions', async () => {
+    const { grantPermissions } = await import('../adb.js');
+    const spawnSpy = vi
+      .spyOn(tools, 'spawn')
+      .mockResolvedValueOnce({
+        stdout: 'package:com.example.app\n',
+      } as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: `requested permissions:\n  android.permission.INTERNET\ninstall permissions:\n`,
+      } as Awaited<ReturnType<typeof tools.spawn>>)
+      .mockResolvedValueOnce({
+        stdout: `Dangerous Permissions:\n  permission:android.permission.CAMERA\n`,
+      } as Awaited<ReturnType<typeof tools.spawn>>);
+
+    await grantPermissions('emulator-5554', 'com.example.app');
+
+    expect(spawnSpy).toHaveBeenCalledTimes(3);
+  });
 });

package/src/__tests__/emulator-startup.test.ts

@@ -10,6 +10,9 @@ describe('emulator startup modes', () => {
         '-no-snapshot-save',
       ])
     );
+    expect(getEmulatorStartupArgs('Pixel_8_API_35', 'default-boot')).not.toEqual(
+      expect.arrayContaining(['-camera-back', 'none'])
+    );
   });
 
   it('builds clean snapshot generation args', () => {

package/src/__tests__/instance.test.ts

@@ -429,6 +429,60 @@ describe('Android platform instance', () => {
     fs.rmSync(appPath, { force: true });
   });
 
+  it('reinstalls the app from HARNESS_APP_PATH when already installed', async () => {
+    const appPath = path.join(os.tmpdir(), 'HarnessPlayground-installed.apk');
+    fs.writeFileSync(appPath, 'apk');
+    vi.stubEnv('HARNESS_APP_PATH', appPath);
+    vi.spyOn(
+      await import('../environment.js'),
+      'ensureAndroidEmulatorEnvironment',
+    ).mockResolvedValue('/tmp/android-sdk');
+    vi.spyOn(adb, 'getDeviceIds').mockResolvedValue(['emulator-5554']);
+    vi.spyOn(adb, 'getEmulatorName').mockResolvedValue('Pixel_8_API_35');
+    vi.spyOn(adb, 'waitForBoot').mockResolvedValue('emulator-5554');
+    vi.spyOn(adb, 'isAppInstalled').mockResolvedValue(true);
+    const uninstallApp = vi
+      .spyOn(adb, 'uninstallApp')
+      .mockResolvedValue(undefined);
+    const installApp = vi.spyOn(adb, 'installApp').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'reversePort').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'setHideErrorDialogs').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'getAppUid').mockResolvedValue(10234);
+    vi.spyOn(sharedPrefs, 'applyHarnessDebugHttpHost').mockResolvedValue(
+      undefined,
+    );
+
+    await expect(
+      getAndroidEmulatorPlatformInstance(
+        {
+          name: 'android',
+          device: {
+            type: 'emulator',
+            name: 'Pixel_8_API_35',
+            avd: {
+              apiLevel: 35,
+              profile: 'pixel_8',
+              diskSize: '1G',
+              heapSize: '1G',
+            },
+          },
+          bundleId: 'com.harnessplayground',
+          activityName: '.MainActivity',
+        },
+        harnessConfig,
+        init,
+      ),
+    ).resolves.toBeDefined();
+
+    expect(uninstallApp).toHaveBeenCalledWith(
+      'emulator-5554',
+      'com.harnessplayground',
+    );
+    expect(installApp).toHaveBeenCalledWith('emulator-5554', appPath);
+
+    fs.rmSync(appPath, { force: true });
+  });
+
   it('throws a HarnessAppPathError when HARNESS_APP_PATH is missing', async () => {
     vi.spyOn(adb, 'getDeviceIds').mockResolvedValue(['emulator-5554']);
     vi.spyOn(adb, 'getEmulatorName').mockResolvedValue('Pixel_8_API_35');
@@ -607,4 +661,138 @@ describe('Android platform instance', () => {
     expect(appMonitor.addListener(listener)).toBeUndefined();
     expect(appMonitor.removeListener(listener)).toBeUndefined();
   });
+
+  it('grants permissions when permissions are enabled for emulator', async () => {
+    vi.spyOn(
+      await import('../environment.js'),
+      'ensureAndroidEmulatorEnvironment',
+    ).mockResolvedValue('/tmp/android-sdk');
+    vi.spyOn(adb, 'getDeviceIds').mockResolvedValue(['emulator-5554']);
+    vi.spyOn(adb, 'getEmulatorName').mockResolvedValue('Pixel_8_API_35');
+    vi.spyOn(adb, 'waitForBoot').mockResolvedValue('emulator-5554');
+    vi.spyOn(adb, 'isAppInstalled').mockResolvedValue(true);
+    vi.spyOn(adb, 'reversePort').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'setHideErrorDialogs').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'getAppUid').mockResolvedValue(10234);
+    vi.spyOn(sharedPrefs, 'applyHarnessDebugHttpHost').mockResolvedValue(
+      undefined,
+    );
+    const grantPermissions = vi
+      .spyOn(adb, 'grantPermissions')
+      .mockResolvedValue(undefined);
+
+    const harnessConfigWithPermissions = {
+      ...harnessConfig,
+      permissions: true,
+    } as HarnessConfig;
+
+    await getAndroidEmulatorPlatformInstance(
+      {
+        name: 'android',
+        device: {
+          type: 'emulator',
+          name: 'Pixel_8_API_35',
+          avd: {
+            apiLevel: 35,
+            profile: 'pixel_8',
+            diskSize: '1G',
+            heapSize: '1G',
+          },
+        },
+        bundleId: 'com.harnessplayground',
+        activityName: '.MainActivity',
+      },
+      harnessConfigWithPermissions,
+      init,
+    );
+
+    expect(grantPermissions).toHaveBeenCalledWith(
+      'emulator-5554',
+      'com.harnessplayground',
+    );
+  });
+
+  it('does not grant permissions when permissions are disabled for emulator', async () => {
+    vi.spyOn(
+      await import('../environment.js'),
+      'ensureAndroidEmulatorEnvironment',
+    ).mockResolvedValue('/tmp/android-sdk');
+    vi.spyOn(adb, 'getDeviceIds').mockResolvedValue(['emulator-5554']);
+    vi.spyOn(adb, 'getEmulatorName').mockResolvedValue('Pixel_8_API_35');
+    vi.spyOn(adb, 'waitForBoot').mockResolvedValue('emulator-5554');
+    vi.spyOn(adb, 'isAppInstalled').mockResolvedValue(true);
+    vi.spyOn(adb, 'reversePort').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'setHideErrorDialogs').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'getAppUid').mockResolvedValue(10234);
+    vi.spyOn(sharedPrefs, 'applyHarnessDebugHttpHost').mockResolvedValue(
+      undefined,
+    );
+    const grantPermissions = vi
+      .spyOn(adb, 'grantPermissions')
+      .mockResolvedValue(undefined);
+
+    await getAndroidEmulatorPlatformInstance(
+      {
+        name: 'android',
+        device: {
+          type: 'emulator',
+          name: 'Pixel_8_API_35',
+          avd: {
+            apiLevel: 35,
+            profile: 'pixel_8',
+            diskSize: '1G',
+            heapSize: '1G',
+          },
+        },
+        bundleId: 'com.harnessplayground',
+        activityName: '.MainActivity',
+      },
+      harnessConfig,
+      init,
+    );
+
+    expect(grantPermissions).not.toHaveBeenCalled();
+  });
+
+  it('grants permissions when permissions are enabled for physical device', async () => {
+    vi.spyOn(adb, 'getDeviceIds').mockResolvedValue(['012345']);
+    vi.spyOn(adb, 'getDeviceInfo').mockResolvedValue({
+      manufacturer: 'motorola',
+      model: 'moto g72',
+    });
+    vi.spyOn(adb, 'isAppInstalled').mockResolvedValue(true);
+    vi.spyOn(adb, 'reversePort').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'setHideErrorDialogs').mockResolvedValue(undefined);
+    vi.spyOn(adb, 'getAppUid').mockResolvedValue(10234);
+    vi.spyOn(sharedPrefs, 'applyHarnessDebugHttpHost').mockResolvedValue(
+      undefined,
+    );
+    const grantPermissions = vi
+      .spyOn(adb, 'grantPermissions')
+      .mockResolvedValue(undefined);
+
+    const harnessConfigWithPermissions = {
+      ...harnessConfig,
+      permissions: true,
+    } as HarnessConfig;
+
+    await getAndroidPhysicalDevicePlatformInstance(
+      {
+        name: 'android-device',
+        device: {
+          type: 'physical',
+          manufacturer: 'motorola',
+          model: 'moto g72',
+        },
+        bundleId: 'com.harnessplayground',
+        activityName: '.MainActivity',
+      },
+      harnessConfigWithPermissions,
+    );
+
+    expect(grantPermissions).toHaveBeenCalledWith(
+      '012345',
+      'com.harnessplayground',
+    );
+  });
 });

package/src/adb-errors.ts

@@ -0,0 +1,47 @@
+export class AdbError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AdbError';
+  }
+}
+
+export class AdbDeviceNotFoundError extends AdbError {
+  constructor(adbId: string) {
+    super(
+      `Android device "${adbId}" not found or not connected. ` +
+      `Run "adb devices" to see available devices.`
+    );
+    this.name = 'AdbDeviceNotFoundError';
+  }
+}
+
+export class AdbAppNotInstalledError extends AdbError {
+  constructor(bundleId: string, adbId: string) {
+    super(
+      `App "${bundleId}" is not installed on device "${adbId}". ` +
+      `Install the app before running tests.`
+    );
+    this.name = 'AdbAppNotInstalledError';
+  }
+}
+
+export class AdbPermissionGrantError extends AdbError {
+  constructor(bundleId: string, permissions: string[], adbId: string) {
+    const permissionList = permissions.join(', ');
+    super(
+      `Failed to grant permissions [${permissionList}] to "${bundleId}" on device "${adbId}". ` +
+      `Verify the app is installed and the device supports these permissions.`
+    );
+    this.name = 'AdbPermissionGrantError';
+  }
+}
+
+export class AdbBinaryNotFoundError extends AdbError {
+  constructor() {
+    super(
+      `adb binary not found or not accessible. ` +
+      `Ensure Android SDK is properly installed and ANDROID_HOME is set.`
+    );
+    this.name = 'AdbBinaryNotFoundError';
+  }
+}

package/src/adb-id.ts

@@ -16,6 +16,10 @@ export const getAdbId = async (
 
   for (const adbId of adbIds) {
     if (isAndroidDeviceEmulator(device)) {
+      if (!isAdbIdEmulator(adbId)) {
+        continue;
+      }
+
       const emulatorName = await adb.getEmulatorName(adbId);
 
       if (emulatorName === device.name) {