@appium/coresim 1.11.1 → 1.13.0

package/src/types.ts

@@ -87,9 +87,10 @@ export type SimPermissionStatus = 'unset' | 'denied' | 'granted' | 'limited';
 
 /**
  * A privacy permission grantable via `NativeSimctl.grantPermission`/`revokePermission`/
- * `resetPermission`. Each is backed by a row in the simulator's own TCC (privacy) database —
- * `location` isn't included since CoreLocation simulation has its own subsystem, not a plain TCC
- * row (see CLAUDE.md).
+ * `resetPermission`. Each except `notifications` is backed by a row in the simulator's own TCC
+ * (privacy) database — `location` isn't included since CoreLocation simulation has its own
+ * subsystem, not a plain TCC row (see CLAUDE.md). `notifications` is SpringBoard's own setting:
+ * changing it restarts SpringBoard, and its status can't be read back via `getPermission`.
  */
 export type SimPermissionService =
   | 'calendar'
@@ -101,6 +102,7 @@ export type SimPermissionService =
   | 'medialibrary'
   | 'microphone'
   | 'motion'
+  | 'notifications'
   | 'photos'
   | 'reminders'
   | 'siri'
@@ -111,23 +113,32 @@ export type SimPermissionService =
  * A device's renderable display, as returned by `NativeSimctl.getDisplays()`.
  */
 export interface SimDisplayInfo {
-  /** Port UUID identifying this display — pass as `getScreenshot`'s `displayId` option to target it. */
+  /** Port UUID identifying this display — pass as a capture API’s `displayId` option to target it. */
   id: string;
-  /** Raw `SimDisplayDescriptorState.displayClass` — 0 is always the primary display. */
+  /** Guest screen ID (`SimScreenProperties.screenID`), when available. Matches XCTest displayID. */
+  screenId?: number;
+  /** Raw `SimDisplayDescriptorState.displayClass` — 0 includes both built-in displays on Duo. */
   displayClass: number;
-  /** Whether this is the primary display (`displayClass === 0`). */
+  /** Whether `displayClass === 0`. Multiple integrated displays may have this value. */
   isMain: boolean;
 }
 
+/** Port UUID string or unsigned 32-bit guest screen ID (XCTest/WDA displayID). */
+export type DisplayId = string | number;
+
+/** Display selection shared by screenshot, recording, and streaming APIs. */
+export interface DisplayOptions {
+  /**
+   * Port UUID from `getDisplays()`, or an unsigned 32-bit guest screen ID (XCTest/WDA displayID).
+   * See [display selection helpers](./utils/display.ts) for validation and resolution semantics.
+   */
+  displayId?: DisplayId;
+}
+
 /** Options for `NativeSimctl.getScreenshot`. */
-export interface ScreenshotOptions {
+export interface ScreenshotOptions extends DisplayOptions {
   /** Image encoding — defaults to `'png'`. */
   format?: 'png' | 'jpeg';
-  /**
-   * Which display to capture, by `id` from `getDisplays()`. Defaults to the primary display
-   * (falling back to the first renderable display if none is primary, e.g. tvOS).
-   */
-  displayId?: string;
   /**
    * JPEG quality as a percentage (0 = smallest/most compressed, 100 = largest/least compressed).
    * Only meaningful with `format: 'jpeg'` — ignored for `'png'`, which is always lossless.
@@ -137,12 +148,7 @@ export interface ScreenshotOptions {
 }
 
 /** Options for `NativeSimctl.startVideoRecording`. */
-export interface VideoRecordingOptions {
-  /**
-   * Which display to record, by `id` from `getDisplays()`. Defaults to the primary display
-   * (falling back to the first renderable display if none is primary, e.g. tvOS).
-   */
-  displayId?: string;
+export interface VideoRecordingOptions extends DisplayOptions {
   /** Video codec — `'h264'` (default) or `'hevc'`. */
   codec?: 'h264' | 'hevc';
   /**
@@ -189,12 +195,7 @@ export interface StopVideoRecordingOptions {
 }
 
 /** Options for `NativeSimctl.startVideoStream`. */
-export interface VideoStreamOptions {
-  /**
-   * Which display to stream, by `id` from `getDisplays()`. Defaults to the primary display
-   * (falling back to the first renderable display if none is primary, e.g. tvOS).
-   */
-  displayId?: string;
+export interface VideoStreamOptions extends DisplayOptions {
   /** Video codec — `'h264'` (default) or `'hevc'`. */
   codec?: 'h264' | 'hevc';
   /**
@@ -213,12 +214,7 @@ export interface VideoStreamOptions {
 }
 
 /** Options for `NativeSimctl.startJpegStream`. */
-export interface JpegStreamOptions {
-  /**
-   * Which display to stream, by `id` from `getDisplays()`. Defaults to the primary display
-   * (falling back to the first renderable display if none is primary, e.g. tvOS).
-   */
-  displayId?: string;
+export interface JpegStreamOptions extends DisplayOptions {
   /**
    * Max frames/sec to poll the framebuffer at — an unchanged frame is never re-encoded, so this
    * is an upper bound, not a guarantee. Must be >= 1. Defaults to 60.
@@ -430,6 +426,7 @@ export interface NativeDeviceHandle {
   deviceTypeIdentifier(): string;
   runtimeIdentifier(): string;
   runtimeRootPath(): string;
+  dataPath(): string;
   boot(options?: Record<string, unknown>): Promise<void>;
   getBootStatus(): Promise<SimBootInfo | null>;
   shutdown(): Promise<void>;

package/src/utils/display.ts

@@ -0,0 +1,67 @@
+import type {DisplayId, NativeDeviceHandle, SimDisplayInfo} from '../types.js';
+
+/**
+ * Validates a capture API's display selection without querying the device.
+ * Strings pass through without UUID syntax or port-existence checks.
+ *
+ * @param displayId — port UUID string, unsigned 32-bit guest screen ID, or `undefined` for default selection
+ * @throws {TypeError} if the value is neither a string, a number, nor `undefined`
+ * @throws {RangeError} if a numeric value is not an unsigned 32-bit integer
+ */
+export function validateDisplayId(displayId: unknown): void {
+  if (displayId !== undefined && typeof displayId !== 'string' && typeof displayId !== 'number') {
+    throw new TypeError('displayId must be a port UUID string or a numeric guest screen ID');
+  }
+  if (typeof displayId === 'number' && (!Number.isInteger(displayId) || displayId < 0 || displayId > 0xffffffff)) {
+    throw new RangeError('A numeric displayId must be an unsigned 32-bit integer');
+  }
+}
+
+/**
+ * Resolves a validated display selection to the port UUID expected by native capture APIs.
+ * UUID strings pass through without enumeration; numeric IDs are matched against a fresh list
+ * of guest screen IDs (XCTest/WDA displayID) on each call. An omitted ID selects the unique `isMain` (class-0) port.
+ * If no class-0 port exists, native capture falls back to the first renderable display.
+ * Call once at recording/stream startup, or on each screenshot capture.
+ *
+ * @param device — native handle for the device whose display ports are queried
+ * @param displayId — selection already checked by {@link validateDisplayId}
+ * @returns the selected port UUID, or `undefined` to retain native fallback when no default port exists
+ * @throws {Error} if a numeric ID has no unique match with a nonempty UUID, or multiple default ports exist
+ */
+export async function resolveDisplayPortId(
+  device: NativeDeviceHandle,
+  displayId: DisplayId | undefined,
+): Promise<string | undefined> {
+  if (typeof displayId === 'string') {
+    return displayId;
+  }
+
+  const displays = await device.getDisplays();
+  if (typeof displayId === 'number') {
+    const matches = displays.filter(({screenId}) => screenId === displayId);
+    if (matches.length !== 1 || !matches[0].id) {
+      throw new Error(
+        `Cannot uniquely resolve guest screen ID ${displayId} to a display port. ${availableDisplayIdsHint(displays)}`,
+      );
+    }
+    return matches[0].id;
+  }
+
+  // Both integrated Duo displays have class 0. Never pick one by port order.
+  const defaults = displays.filter(({isMain}) => isMain);
+  if (defaults.length > 1) {
+    throw new Error(
+      `Multiple default display ports are available; specify displayId. ${availableDisplayIdsHint(displays)}`,
+    );
+  }
+  return defaults[0]?.id;
+}
+
+/** Formats the already-fetched screen ID/port UUID pairs for display-selection errors. */
+function availableDisplayIdsHint(displays: SimDisplayInfo[]): string {
+  if (displays.length === 0) {
+    return 'Available display IDs: none';
+  }
+  return `Available display IDs: ${JSON.stringify(displays.map(({id, screenId}) => ({screenId, id})))}`;
+}

package/src/utils/index.ts

@@ -1,2 +1,3 @@
 export {getPkgRoot, PACKAGE_NAME} from './pkg-root.js';
 export {runCatchingAsync, toTypedError} from './run-catching.js';
+export {resolveDisplayPortId, validateDisplayId} from './display.js';