feat: filter device allocation by deviceType and osVersion constraint expressions

docs/src/test/configuration.md

@@ -37,10 +37,33 @@ Which device to run on and which app to drive.
 | `platform` | `'ios' \| 'android'` | — | Target platform |
 | `deviceId` | `string` | — | Specific device identifier (local drivers only) |
 | `deviceName` | `RegExp` | — | Match a device by name, e.g. `/iPhone 17/` |
+| `deviceType` | `'simulator' \| 'emulator' \| 'real'` | — | Restrict to simulators, emulators, or real devices |
+| `osVersion` | `string` | — | OS version constraint — see [OS version constraints](#os-version-constraints) |
 | `bundleId` | `string` | — | App bundle ID to launch |
 | `installApps` | `string \| string[]` | — | App paths (APK/IPA) to install before launching |
 | `autoAppLaunch` | `boolean` | `true` | Launch the app automatically after connecting |
 
+### OS version constraints
+
+`osVersion` accepts a bare version or a comparator expression:
+
+| Expression | Matches |
+| --- | --- |
+| `'17'` | Any 17.x release (≥ 17, < 18) |
+| `'26.0'` | Exactly 26.0 (26.0.1 matches, 26.1 does not) |
+| `'>=17'` | 17 or newer |
+| `'>=17 <19'` | 17 or 18, not 19 |
+
+A bare version is a prefix match. Comparator expressions combine at most one lower bound (`>=` or `>`) and one upper bound (`<` or `<=`), separated by a space.
+
+```ts
+export default defineConfig({
+  platform: 'ios',
+  deviceType: 'real',
+  osVersion: '>=17 <19',
+});
+```
+
 ## Driver
 
 The driver decides where tests run — a local device via mobilecli, or a cloud device. Pass an
@@ -162,4 +185,4 @@ export default defineConfig({
 });
 ```
 
-The project `use` block accepts `platform`, `deviceId`, `deviceName`, `bundleId`, `installApps`, `animations`, `actionTimeout`, `appLaunchTimeout`, and `installTimeout`. Projects can also override `timeout`, `testDir`, `testMatch`, `testIgnore`, `outputDir`, `retries`, `grep`, `grepInvert`, and declare `dependencies` on other projects. See [Projects](./projects.md) for the full matrix.
+The project `use` block accepts `platform`, `deviceId`, `deviceName`, `deviceType`, `osVersion`, `bundleId`, `installApps`, `animations`, `actionTimeout`, `appLaunchTimeout`, and `installTimeout`. Projects can also override `timeout`, `testDir`, `testMatch`, `testIgnore`, `outputDir`, `retries`, `grep`, `grepInvert`, and declare `dependencies` on other projects. See [Projects](./projects.md) for the full matrix.

docs/src/test/projects.md

@@ -59,6 +59,8 @@ The `use` block inside each project accepts the same options as the top-level co
 | `installApps` | APK or IPA/ZIP path(s) to install before tests run |
 | `deviceId` | Exact device ID to pin this project to (local drivers only) |
 | `deviceName` | Regex to match a specific device |
+| `deviceType` | `'simulator'`, `'emulator'` or `'real'` |
+| `osVersion` | OS version constraint, e.g. `'17'`, `'26.0'` or `'>=17 <19'` |
 
 A common pattern is to share `bundleId` and `timeout` at the top level, and only specify `platform` and `installApps` per project:
 

packages/driver-mobilecli/src/driver.test.ts

@@ -3,6 +3,7 @@ import { writeFileSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { MobilecliDriver } from './driver.js';
+import { NoDeviceAvailableError, type DeviceInfo } from '@mobilewright/protocol';
 
 const ZIP_MAGIC = Buffer.from([0x50, 0x4B, 0x03, 0x04]);
 const tmpDir = mkdtempSync(join(tmpdir(), 'mw-driver-test-'));
@@ -364,3 +365,68 @@ test.describe('MobilecliDriver.applyDeviceSettings()', () => {
     ]);
   });
 });
+
+test.describe('MobilecliDriver.allocate()', () => {
+  function createDriverWithDevices(devices: Partial<DeviceInfo>[]): MobilecliDriver {
+    const driver = new MobilecliDriver();
+    driver.listDevices = async () =>
+      devices.map((d, i) => ({
+        id: d.id ?? `device-${i}`,
+        name: d.name ?? `Device ${i}`,
+        platform: d.platform ?? 'ios',
+        type: d.type ?? 'simulator',
+        state: d.state ?? 'online',
+        model: d.model,
+        osVersion: d.osVersion,
+      }));
+    return driver;
+  }
+
+  test('picks a real device over a simulator when deviceType is "real"', async () => {
+    const driver = createDriverWithDevices([
+      { id: 'sim-1', type: 'simulator' },
+      { id: 'real-1', type: 'real' },
+    ]);
+
+    const allocated = await driver.allocate({ platform: 'ios', deviceType: 'real' }, new Set());
+
+    expect(allocated.deviceId).toBe('real-1');
+  });
+
+  test('throws NoDeviceAvailableError when no device matches the deviceType', async () => {
+    const driver = createDriverWithDevices([{ id: 'sim-1', type: 'simulator' }]);
+
+    await expect(driver.allocate({ platform: 'ios', deviceType: 'real' }, new Set())).rejects.toThrow(
+      NoDeviceAvailableError,
+    );
+  });
+
+  test('picks the device whose OS version satisfies the expression', async () => {
+    const driver = createDriverWithDevices([
+      { id: 'old', osVersion: '16.4' },
+      { id: 'wanted', osVersion: '17.5' },
+      { id: 'too-new', osVersion: '18.0' },
+    ]);
+
+    const allocated = await driver.allocate({ platform: 'ios', osVersion: '17' }, new Set());
+
+    expect(allocated.deviceId).toBe('wanted');
+  });
+
+  test('a device that does not report an OS version never matches an osVersion filter', async () => {
+    const driver = createDriverWithDevices([{ id: 'unknown-version', osVersion: undefined }]);
+
+    await expect(driver.allocate({ platform: 'ios', osVersion: '17' }, new Set())).rejects.toThrow(
+      NoDeviceAvailableError,
+    );
+  });
+});
+
+test('an invalid osVersion expression throws a parse error even when no devices are eligible', async () => {
+  const driver = new MobilecliDriver();
+  driver.listDevices = async () => [];
+
+  await expect(driver.allocate({ platform: 'ios', osVersion: 'latest' }, new Set())).rejects.toThrow(
+    /invalid OS version/,
+  );
+});

packages/driver-mobilecli/src/driver.ts

@@ -31,7 +31,7 @@ import type {
   WebViewInfo,
   WebViewSession,
 } from '@mobilewright/protocol';
-import { NoDeviceAvailableError } from '@mobilewright/protocol';
+import { NoDeviceAvailableError, osVersionSatisfies, parseOsVersion } from '@mobilewright/protocol';
 import { RpcClient } from './rpc-client.js';
 import { resolveMobilecliBinary } from './resolve-binary.js';
 import { ensureMobilecliReachable, type ServerHandle } from './server.js';
@@ -427,6 +427,12 @@ export class MobilecliDriver implements MobilewrightSession, DeviceAllocator {
     criteria: AllocationCriteria,
     takenDeviceIds: ReadonlySet<string>,
   ): Promise<AllocatedDevice> {
+    if (criteria.osVersion) {
+      // Validate up front: with zero eligible devices the per-device filter below
+      // never parses the expression, and a malformed one would masquerade as a
+      // retriable NoDeviceAvailableError.
+      parseOsVersion(criteria.osVersion);
+    }
     const devices = await this.listDevices(criteria.platform ? { platform: criteria.platform } : undefined);
 
     const namePattern = criteria.deviceNamePattern ? new RegExp(criteria.deviceNamePattern) : undefined;
@@ -436,6 +442,8 @@ export class MobilecliDriver implements MobilewrightSession, DeviceAllocator {
       .filter((d) => !takenDeviceIds.has(d.id))
       .filter((d) => !criteria.deviceId || d.id === criteria.deviceId)
       .filter((d) => !namePattern || namePattern.test(d.name))
+      .filter((d) => !criteria.deviceType || d.type === criteria.deviceType)
+      .filter((d) => !criteria.osVersion || (d.osVersion !== undefined && osVersionSatisfies(d.osVersion, criteria.osVersion)))
       .at(0);
 
     if (!match) {

packages/driver-mobilenext/src/build-filters.test.ts

@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+import { buildFilters } from './driver.js';
+
+test('deviceType criteria becomes a type EQUALS filter', () => {
+  const filters = buildFilters({ platform: 'ios', deviceType: 'real' });
+
+  expect(filters).toContainEqual({ attribute: 'type', operator: 'EQUALS', value: 'real' });
+});
+
+test('a bare osVersion becomes inclusive-lower and exclusive-upper version filters', () => {
+  const filters = buildFilters({ platform: 'ios', osVersion: '17' });
+
+  expect(filters).toContainEqual({ attribute: 'version', operator: 'GREATER_THAN_OR_EQUALS', value: '17' });
+  expect(filters).toContainEqual({ attribute: 'version', operator: 'LESS_THAN', value: '18' });
+});
+
+test('comparator osVersion expressions map onto the matching fleet operators', () => {
+  expect(buildFilters({ platform: 'android', osVersion: '>16' })).toContainEqual(
+    { attribute: 'version', operator: 'GREATER_THAN', value: '16' },
+  );
+  expect(buildFilters({ platform: 'android', osVersion: '<=16' })).toContainEqual(
+    { attribute: 'version', operator: 'LESS_THAN_OR_EQUALS', value: '16' },
+  );
+});
+
+test('an invalid osVersion expression throws before reaching the fleet API', () => {
+  expect(() => buildFilters({ platform: 'ios', osVersion: 'latest' })).toThrow();
+});

packages/driver-mobilenext/src/driver.ts

@@ -29,6 +29,7 @@ import type {
   TestObserver,
   ViewNode,
 } from '@mobilewright/protocol';
+import { parseOsVersion } from '@mobilewright/protocol';
 import { RpcClient } from './rpc-client.js';
 import { FleetApiClient, type DeviceFilter } from './fleet-api.js';
 import { MobileNextTestObserver, type MobileNextTestResultConfig } from './observer.js';
@@ -108,7 +109,7 @@ export interface MobileNextDriverOptions {
   uploadTimeout?: number;
 }
 
-function buildFilters(criteria: AllocationCriteria): DeviceFilter[] {
+export function buildFilters(criteria: AllocationCriteria): DeviceFilter[] {
   // The fleet API requires exactly one platform filter, so a missing platform is a caller error —
   // fail loudly instead of silently constraining every allocation to iOS.
   if (!criteria.platform) {
@@ -128,6 +129,18 @@ function buildFilters(criteria: AllocationCriteria): DeviceFilter[] {
   if (criteria.deviceNamePattern) {
     filters.push({ attribute: 'name', operator: 'CONTAINS', value: criteria.deviceNamePattern });
   }
+  if (criteria.deviceType) {
+    filters.push({ attribute: 'type', operator: 'EQUALS', value: criteria.deviceType });
+  }
+  if (criteria.osVersion) {
+    const range = parseOsVersion(criteria.osVersion);
+    if (range.min) {
+      filters.push({ attribute: 'version', operator: range.min.inclusive ? 'GREATER_THAN_OR_EQUALS' : 'GREATER_THAN', value: range.min.version });
+    }
+    if (range.max) {
+      filters.push({ attribute: 'version', operator: range.max.inclusive ? 'LESS_THAN_OR_EQUALS' : 'LESS_THAN', value: range.max.version });
+    }
+  }
   return filters;
 }
 

packages/mobilewright/src/config.ts

@@ -25,6 +25,10 @@ export interface MobilewrightUseOptions {
   deviceId?: string;
   /** Regex to match device name. */
   deviceName?: RegExp;
+  /** Restrict to simulators, emulators, or real devices. */
+  deviceType?: 'simulator' | 'emulator' | 'real';
+  /** OS version constraint, e.g. "17" (any 17.x), "26.0" (exactly 26.0) or ">=17 <19". */
+  osVersion?: string;
   /** App bundle ID for this project. */
   bundleId?: string;
   /** App paths (APK/IPA) to install for this project. Overrides top-level installApps. */
@@ -79,6 +83,10 @@ export interface MobilewrightConfig {
   deviceId?: string;
   /** Regex to match device name (e.g. /iPhone 17/). */
   deviceName?: RegExp;
+  /** Restrict to simulators, emulators, or real devices. */
+  deviceType?: 'simulator' | 'emulator' | 'real';
+  /** OS version constraint, e.g. "17" (any 17.x), "26.0" (exactly 26.0) or ">=17 <19". */
+  osVersion?: string;
   /** Default app bundle ID. */
   bundleId?: string;
   /** App paths (APK/IPA) to install on the device before launching. */

packages/mobilewright/src/device-pool/application/device-pool.test.ts

@@ -233,3 +233,44 @@ test('allocation that exceeds allocationTimeoutMs rejects with timeout error', a
 
   await expect(pool.allocate({ platform: 'ios' })).rejects.toThrow(/timed out/i);
 });
+
+test('a released simulator slot is not reused for a waiter demanding a real device', async () => {
+  const driver = makeDriver([
+    { deviceId: 'sim-1', platform: 'ios', type: 'simulator' },
+    { deviceId: 'real-1', platform: 'ios', type: 'real' },
+  ]);
+  const pool = new DevicePool({ driver, maxSlots: 2 });
+
+  const first = await pool.allocate({ platform: 'ios', deviceType: 'simulator' });
+  await pool.release(first.allocationId);
+  const second = await pool.allocate({ platform: 'ios', deviceType: 'real' });
+
+  expect(second.deviceId).toBe('real-1');
+});
+
+test('a released slot is not reused for a waiter whose osVersion the device does not satisfy', async () => {
+  const driver = makeDriver([
+    { deviceId: 'ios16', platform: 'ios', osVersion: '16.4' },
+    { deviceId: 'ios17', platform: 'ios', osVersion: '17.5' },
+  ]);
+  const pool = new DevicePool({ driver, maxSlots: 2 });
+
+  const first = await pool.allocate({ platform: 'ios' });
+  await pool.release(first.allocationId);
+  const second = await pool.allocate({ platform: 'ios', osVersion: '17' });
+
+  expect(second.deviceId).toBe('ios17');
+});
+
+test('a released slot is reused when it satisfies the deviceType and osVersion criteria', async () => {
+  const driver = makeDriver([
+    { deviceId: 'sim-17', platform: 'ios', type: 'simulator', osVersion: '17.5' },
+  ]);
+  const pool = new DevicePool({ driver, maxSlots: 2 });
+
+  const first = await pool.allocate({ platform: 'ios' });
+  await pool.release(first.allocationId);
+  const second = await pool.allocate({ platform: 'ios', deviceType: 'simulator', osVersion: '>=17' });
+
+  expect(second.deviceId).toBe('sim-17');
+});

packages/mobilewright/src/device-pool/application/device-pool.ts

@@ -1,4 +1,5 @@
 import type { DeviceAllocator } from '@mobilewright/protocol';
+import { osVersionSatisfies } from '@mobilewright/protocol';
 import { DeviceSlot } from '../domain/device-slot.js';
 import { Allocation } from '../domain/allocation.js';
 import { NoDeviceAvailableError } from './ports.js';
@@ -230,5 +231,11 @@ function slotMatches(slot: DeviceSlot, criteria: AllocationCriteria): boolean {
   if (criteria.deviceId && slot.deviceId !== criteria.deviceId) {
     return false;
   }
+  if (criteria.deviceType && slot.type !== criteria.deviceType) {
+    return false;
+  }
+  if (criteria.osVersion && (slot.osVersion === undefined || !osVersionSatisfies(slot.osVersion, criteria.osVersion))) {
+    return false;
+  }
   return true;
 }

packages/protocol/src/driver.ts

@@ -39,6 +39,10 @@ export interface AllocationCriteria {
   /** Regex source (`RegExp.prototype.source`) matched against device name. */
   deviceNamePattern?: string;
   deviceId?: string;
+  /** Restrict to simulators, emulators, or real devices. */
+  deviceType?: DeviceType;
+  /** OS version constraint expression, e.g. "17", "26.0" or ">=17 <19". See `parseOsVersion`. */
+  osVersion?: string;
 }
 
 export interface AllocatedDevice {

packages/protocol/src/index.ts

@@ -1,3 +1,5 @@
 export type * from './types.js';
 export type * from './driver.js';
 export { NoDeviceAvailableError } from './driver.js';
+export { parseOsVersion, osVersionSatisfies } from './os-version.js';
+export type { OsVersionBound, OsVersionRange } from './os-version.js';