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.
- Java
- Python
- JavaScript (WebdriverIO)
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);
options = UiAutomator2Options()
options.platform_name = "Android"
options.automation_name = "UiAutomator2"
# Keep your other Digital.ai settings in this dictionary.
digitalai_options = {
"deviceQuery": "@os='android' and @modelName='Samsung Galaxy S25' and @versionnumber='15.0'",
}
options.set_capability("digitalai:options", digitalai_options)
const capabilities = {
platformName: "Android",
"appium:automationName": "UiAutomator2",
"digitalai:options": {
// Keep your other Digital.ai settings here.
deviceQuery: "@os='android' and @modelName='Samsung Galaxy S25' and @versionnumber='15.0'",
},
};
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.
- Java
- Python
- JavaScript (WebdriverIO)
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);
options = XCUITestOptions()
options.platform_name = "iOS"
options.automation_name = "XCUITest"
# Keep your other Digital.ai settings in this dictionary.
digitalai_options = {
"deviceQuery": "@os='ios' and contains(@name,'18 Plus')",
}
options.set_capability("digitalai:options", digitalai_options)
const capabilities = {
platformName: "iOS",
"appium:automationName": "XCUITest",
"digitalai:options": {
// Keep your other Digital.ai settings here.
deviceQuery: "@os='ios' and contains(@name,'18 Plus')",
},
};
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
| Property | Meaning |
|---|---|
os | Operating system. iOS or Android. |
serialnumber | Device serial identifier; mainly used for real devices. How to find the Serial Number. |
version | Full OS version, including minor and patch details, such as 15.0.1. |
versionnumber | Major OS version, such as 15.0 for Android 15. |
category | Device category: PHONE or TABLET. |
emulator | Use true to target virtual devices, applicable to both iOS and Android. |
modelName | Marketing model name. |
model | Model identifier. |
dhmlocation | Configured host-machine location; applies to real devices. |
dhmName | Targets specific DHMs (real devices) or EHMs (virtual devices)—the individual machines hosting the mobile devices. |
manufacture | Manufacturer. |
name | Device name as seen on the platform. |
tag | Administrator-assigned tag. Add Device Tags. |
region | Host-machine region. |
Select a Device from a Specific DHM
Use the @dhmName property to direct test execution to devices on a particular DHM:
- Java
- Python
- JavaScript (WebdriverIO)
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);
# Keep your other Digital.ai settings in this dictionary.
digitalai_options = {
"deviceQuery": "@os='ios' and @dhmName='SpecificDHM-001'",
}
options.set_capability("digitalai:options", digitalai_options)
"digitalai:options": {
// Keep your other Digital.ai settings here.
deviceQuery: "@os='ios' and @dhmName='SpecificDHM-001'",
},
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 requirement | Example condition |
|---|---|
| Android 15, without pinning a minor or patch version | @versionnumber='15.0' |
| An exact full OS version | @version='15.0.1' |
Query examples
| Select | Query |
|---|---|
| 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 group | tag='regression' |
| Devices with both tags | tag='smoke' and tag='regression' |
Troubleshoot device selection
| Symptom | What to check |
|---|---|
| No matching device is allocated | Begin with only the OS condition. Confirm that matching devices are accessible and available, then add conditions one at a time. |
| Query appears to be ignored | Inspect the outgoing capabilities. Confirm that deviceQuery is inside digitalai:options and spelled correctly. |
| Tag query matches no devices | Use tag without @ and confirm that the tag is assigned to the intended devices. |
| Model or version query matches no devices | Check the exact inventory value. A marketing name, hardware model identifier, and device name are different attributes. |
| Unexpected device is selected | Remove 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.