feat: add deterministic device permissions API

README.md

@@ -55,6 +55,30 @@ const config = {
 export default config;
 ```
 
+## Device Permissions Fixture
+
+Harness now exposes a deterministic `device.permissions` API for test setup:
+
+```ts
+import { device } from 'react-native-harness';
+
+await device.permissions.grant('microphone');
+await device.permissions.revoke('microphone');
+await device.permissions.reset('microphone');
+
+await device.permissions.grantAll();
+await device.permissions.denyAll();
+await device.permissions.resetAll();
+```
+
+Platform behavior:
+
+- Android emulator and physical device: named permissions and bulk operations use host-side ADB commands.
+- iOS simulator: named permissions and bulk operations use `xcrun simctl privacy` for supported simulator services.
+- iOS physical device: named permission calls warn and no-op; bulk calls configure XCTest Agent prompt handling for future permission prompts.
+
+Existing `permissions: true` config continues to work and now maps to `grantAll()` semantics through the same host-side permission controller.
+
 ## Documentation
 
 The documentation is available at [react-native-harness.dev](https://react-native-harness.dev). You can also use the following links to jump to specific topics:

packages/bridge/src/client.ts

@@ -27,6 +27,12 @@ export type HarnessHandle = {
   reportReady: (device: DeviceDescriptor) => void;
   /** Forward a test or bundler event to the CLI. */
   emitEvent: (event: BridgeEvents) => void;
+  applyDevicePermission: (
+    command: Parameters<BridgeServerFunctions['device.permissions.apply']>[0],
+  ) => ReturnType<BridgeServerFunctions['device.permissions.apply']>;
+  revertDevicePermission: (
+    mutationId: string,
+  ) => ReturnType<BridgeServerFunctions['device.permissions.revert']>;
   /** Send a screenshot to the CLI and receive a file reference for snapshot comparison. */
   transferScreenshot: (
     data: Uint8Array,
@@ -96,6 +102,9 @@ export const connectToHarness = (
       resolve({
         reportReady: (device) => void rpc.reportReady(device),
         emitEvent: (event) => void rpc.emitEvent(event.type, event),
+        applyDevicePermission: (command) => rpc['device.permissions.apply'](command),
+        revertDevicePermission: (mutationId) =>
+          rpc['device.permissions.revert'](mutationId),
         transferScreenshot: async (data, metadata) => {
           const transferId = generateTransferId();
           ws.send(createBinaryFrame(transferId, data));

packages/bridge/src/server.ts

@@ -159,6 +159,27 @@ export const createHarnessBridge = async (
       emitEvent: (_, data) => {
         emitter.emit('event', data);
       },
+      'device.permissions.apply': async (command) => {
+        const deviceState = context.getDeviceState();
+        if (!deviceState) {
+          throw new Error(
+            `device.permissions is not supported by runner "${context.platform.name}".`,
+          );
+        }
+
+        const result = await deviceState.permissions.apply(command);
+        return { mutationId: result.mutation?.id, warning: result.warning };
+      },
+      'device.permissions.revert': async (mutationId) => {
+        const deviceState = context.getDeviceState();
+        if (!deviceState) {
+          throw new Error(
+            `device.permissions is not supported by runner "${context.platform.name}".`,
+          );
+        }
+
+        await deviceState.permissions.revert(mutationId);
+      },
       'device.screenshot.receive': (ref) => receiveScreenshot(binaryStore, ref),
       'test.matchImageSnapshot': (screenshot, testPath, opts) =>
         matchImageSnapshot(screenshot, testPath, opts, context.platform.name),
@@ -201,7 +222,6 @@ export const createHarnessBridge = async (
             functionName,
             args,
           );
-          throw error;
         },
         onTimeoutError: (fn, args) => {
           throw new DeviceNotRespondingError(fn, args);

packages/bridge/src/shared.ts

@@ -4,7 +4,11 @@ import type {
 } from './shared/test-runner.js';
 import type { TestCollectorEvents } from './shared/test-collector.js';
 import type { BundlerEvents } from './shared/bundler.js';
-import type { HarnessPlatform } from '@react-native-harness/platforms';
+import type {
+  DevicePermissionCommand,
+  DeviceStateController,
+  HarnessPlatform,
+} from '@react-native-harness/platforms';
 
 export const HARNESS_BRIDGE_PATH = '/__harness';
 
@@ -150,6 +154,10 @@ export type ScreenshotData = BinaryDataReference;
 export type BridgeServerFunctions = {
   reportReady: (device: DeviceDescriptor) => void;
   emitEvent: (event: BridgeEvents['type'], data: BridgeEvents) => void;
+  'device.permissions.apply': (
+    command: DevicePermissionCommand,
+  ) => Promise<{ mutationId?: string; warning?: string }>;
+  'device.permissions.revert': (mutationId: string) => Promise<void>;
   'device.screenshot.receive': (
     reference: BinaryDataReference,
     metadata: { width: number; height: number }
@@ -163,5 +171,6 @@ export type BridgeServerFunctions = {
 };
 
 export type HarnessContext = {
+  getDeviceState: () => DeviceStateController | undefined;
   platform: HarnessPlatform;
 };

packages/jest/src/__tests__/bridge.test.ts

@@ -8,14 +8,18 @@ import type { HarnessBridge } from '@react-native-harness/bridge/server';
 import { createHarnessBridge } from '@react-native-harness/bridge/server';
 import { connectToHarness } from '@react-native-harness/bridge/client';
 import type { HarnessContext } from '@react-native-harness/bridge';
+import type { DeviceStateController } from '@react-native-harness/platforms';
 
-const makeContext = (): HarnessContext => ({
+const makeContext = (
+  deviceState?: DeviceStateController,
+): HarnessContext => ({
   platform: {
     name: 'ios',
     platformId: 'ios',
     runner: '/dev/null',
     config: {},
   },
+  getDeviceState: () => deviceState,
 });
 
 // ---------------------------------------------------------------------------
@@ -153,6 +157,64 @@ describe('bridge: createHarnessBridge + connectToHarness', () => {
     });
   });
 
+  describe('device permissions RPCs', () => {
+    it('applies permission mutations through the host-side controller', async () => {
+      const apply = vi.fn(async () => ({
+        mutation: {
+          id: 'mutation-1',
+          revert: vi.fn(async () => undefined),
+        },
+      }));
+      const revert = vi.fn(async () => undefined);
+
+      bridge.dispose();
+      bridge = await createHarnessBridge({
+        port: 0,
+        context: makeContext({
+          permissions: {
+            apply,
+            revert,
+            resetOutstanding: vi.fn(async () => undefined),
+          },
+        }),
+      });
+      bridgePort = (bridge.ws.address() as { port: number }).port;
+
+      const handle = await connect();
+
+      await expect(
+        handle.applyDevicePermission({
+          kind: 'permission',
+          permission: 'microphone',
+          decision: 'grant',
+        }),
+      ).resolves.toEqual({ mutationId: 'mutation-1' });
+
+      await handle.revertDevicePermission('mutation-1');
+
+      expect(apply).toHaveBeenCalledWith({
+        kind: 'permission',
+        permission: 'microphone',
+        decision: 'grant',
+      });
+      expect(revert).toHaveBeenCalledWith('mutation-1');
+      handle.disconnect();
+    });
+
+    it('returns a clear error when no device-state controller exists', async () => {
+      const handle = await connect();
+
+      await expect(
+        handle.applyDevicePermission({
+          kind: 'permission-all',
+          decision: 'grant',
+        }),
+      ).rejects.toThrow('device.permissions is not supported by runner "ios".');
+
+      handle.disconnect();
+    });
+  });
+
   describe('bridge events', () => {
     it('emitEvent on app side fires the event listener on bridge', async () => {
       const onEvent = vi.fn();

packages/jest/src/__tests__/fixtures/mock-platform-runner.ts

@@ -0,0 +1,23 @@
+import type {
+  HarnessPlatformInitOptions,
+  HarnessPlatformRunner,
+} from '@react-native-harness/platforms';
+import type { Config as HarnessConfig } from '@react-native-harness/config';
+
+declare global {
+  var __HARNESS_TEST_PLATFORM_RUNNER__:
+    | HarnessPlatformRunner
+    | undefined;
+}
+
+export default async function mockPlatformRunner(
+  _platformConfig: Record<string, unknown>,
+  _harnessConfig: HarnessConfig,
+  _init: HarnessPlatformInitOptions,
+): Promise<HarnessPlatformRunner> {
+  if (!globalThis.__HARNESS_TEST_PLATFORM_RUNNER__) {
+    throw new Error('Missing __HARNESS_TEST_PLATFORM_RUNNER__ test fixture');
+  }
+
+  return globalThis.__HARNESS_TEST_PLATFORM_RUNNER__;
+}