Skip to main content

Device Queries

Device queries let you describe the combination of device characteristics your test needs, from a broad group of suitable devices to a specific model and operating system version. Instead of tying every test to a fixed device identifier, you define the selection criteria and let the cloud select a matching device.

The level of specificity depends on what you are testing. For a regression run, you might accept any iPhone simulator. Reproducing a device-specific issue might require a real Samsung Galaxy S25 running a particular Android version. Queries let you express those requirements.

Broader queries give the cloud more matching devices to choose from. Narrower queries help you reproduce a particular configuration.

For example, start with any available Android device, then narrow the selection to a model and OS version:

@os='android'

@os='android' and @modelName='Samsung Galaxy S25' and @versionnumber='15.0'

Add a query to your capabilities​

Set deviceQuery inside digitalai:options. Appium capabilities continue to define the platform and automation driver.

The snippets below show only the relevant capability setup for Appium 3. Add the query to the digitalai:options object in your existing test configuration, preserving its other settings. Connection, authentication, and session creation are covered in separate documentation.

Android​

Select a Galaxy S25 with the specified Android version. Replace the model and version with values from your inventory.

UiAutomator2Options options = new UiAutomator2Options();
options.setPlatformName("Android");
options.setAutomationName("UiAutomator2");

Map<String, Object> digitalaiOptions = new HashMap<>();
// Keep your other Digital.ai settings in this map.
digitalaiOptions.put(
"deviceQuery",
"@os='android' and @modelName='Samsung Galaxy S25' and @versionnumber='15.0'"
);
options.setCapability("digitalai:options", digitalaiOptions);

Android virtual devices​

Add @emulator='true' to target Android virtual devices. Combine it with model, OS version, or name conditions to narrow the selection.

Select a Samsung Galaxy S26 virtual device:

@os='android' and @emulator='true' and @modelName='Samsung Galaxy S26'

@os='android' and @emulator='true' and @modelName='Samsung Galaxy S26' and @versionnumber='15.0'

Not all properties apply to virtual devices: serialnumber is used for real devices, and dhmlocation applies to real devices. Avoid using these properties to target virtual devices.

iOS​

Select an iOS device whose name contains 18 Plus, without specifying an OS version or an explicit modelName condition.

XCUITestOptions options = new XCUITestOptions();
options.setPlatformName("iOS");
options.setAutomationName("XCUITest");

Map<String, Object> digitalaiOptions = new HashMap<>();
// Keep your other Digital.ai settings in this map.
digitalaiOptions.put("deviceQuery", "@os='ios' and contains(@name,'18 Plus')");
options.setCapability("digitalai:options", digitalaiOptions);

iOS virtual devices​

Add @emulator='true' to target iOS virtual devices.

Select an iOS virtual device whose model name contains Pro Max:

@os='ios' and @emulator='true' and contains(@modelName,'Pro Max')

This query leaves the specific Pro Max model and OS version open.

As with Android virtual devices, avoid serialnumber and dhmlocation when targeting simulators.

Query syntax​

Queries use XPath-style expressions:

@property='value' and @otherProperty='value'

Prefix device attributes with @. Tags are the exception: use tag='value'. Quote string values and join conditions with and. Use contains() for a partial text match or starts-with() for a prefix match.

Supported properties​

PropertyMeaning
osOperating system. iOS or Android.
serialnumberDevice serial identifier; mainly used for real devices. How to find the Serial Number.
versionFull OS version, including minor and patch details, such as 15.0.1.
versionnumberMajor OS version, such as 15.0 for Android 15.
categoryDevice category: PHONE or TABLET.
emulatorUse true to target virtual devices, applicable to both iOS and Android.
modelNameMarketing model name.
modelModel identifier.
dhmlocationConfigured host-machine location; applies to real devices.
dhmNameTargets specific DHMs (real devices) or EHMs (virtual devices)—the individual machines hosting the mobile devices.
manufactureManufacturer.
nameDevice name as seen on the platform.
tagAdministrator-assigned tag. Add Device Tags.
regionHost-machine region.

Select a Device from a Specific DHM​

Use the @dhmName property to direct test execution to devices on a particular DHM:

Map<String, Object> digitalaiOptions = new HashMap<>();
// Keep your other Digital.ai settings in this map.
digitalaiOptions.put("deviceQuery", "@os='ios' and @dhmName='SpecificDHM-001'");
options.setCapability("digitalai:options", digitalaiOptions);

This query ensures the test runs on an iOS device connected to the specified DHM machine, useful in multi-DHM deployments where you need to control which machine hosts the test execution.

Major version versus full version​

Use versionnumber when the major OS version is what matters. For example, @versionnumber='15.0' targets the Android 15 major version without requiring a particular minor or patch version.

Use version when you need an exact OS release, including its minor and patch details. For example, @version='15.0.1' targets that full version rather than the broader major-version group. This value is illustrative; use the full version recorded in your inventory.

Selection requirementExample condition
Android 15, without pinning a minor or patch version@versionnumber='15.0'
An exact full OS version@version='15.0.1'

Query examples​

SelectQuery
Android devices@os='android'
iOS devices@os='ios'
Android tablets@os='android' and @category='TABLET'
iOS devices whose name contains 18 Plus@os='ios' and contains(@name,'18 Plus')
A specific model and OS version@os='android' and @modelName='Samsung Galaxy S25' and @versionnumber='15.0'
Devices in a regression grouptag='regression'
Devices with both tagstag='smoke' and tag='regression'

Troubleshoot device selection​

SymptomWhat to check
No matching device is allocatedBegin with only the OS condition. Confirm that matching devices are accessible and available, then add conditions one at a time.
Query appears to be ignoredInspect the outgoing capabilities. Confirm that deviceQuery is inside digitalai:options and spelled correctly.
Tag query matches no devicesUse tag without @ and confirm that the tag is assigned to the intended devices.
Model or version query matches no devicesCheck the exact inventory value. A marketing name, hardware model identifier, and device name are different attributes.
Unexpected device is selectedRemove conflicting device selectors and inspect the device attributes used in your query.
Help and Feedback

Help

If you didn’t find what you were looking for in our documentation, reach out to our Support Team for assistance.

Support & Maintenance

To learn about our support model, see Support and Maintenance.

Feedback

If there are product ideas you’d like to submit for us to consider, head to our Ideas Space.