Job Payload Reference

Overview

The job payload is a JSON object submitted to the job creation endpoint to trigger automated test execution on RobusTest Hub.

Endpoint:

POST /v3/job/new?accesskey=<ACCESS_KEY>

Full Payload Examples

Android (Espresso)

{
    "project": "<project_id>",
    "identifier": "<job_identifier>",
    "desc": "<job_description>",
    "priority": 0,
    "type": "Espresso",
    "runMode": "distributed",
    "runSetting": "<run_setting_id>",
    "build": {
        "aut": "<aut_build_id>",
        "test": "<test_build_id>"
    },
    "setting": {
        "performance": {
            "enableAppVitals": true
        },
        "job": {
            "addMoreDevices": false,
            "retryOnSameDevice": false
        }
    },
    "devices": {
        "deviceQueries": [
            {
                "minDeviceCount": 1,
                "maxDeviceCount": 5
            }
        ],
        "devicesGroupIDs": ["allEligibleGroups"],
        "ids": ["<device_id_1>", "<device_id_2>"],
        "limitToMaxDevice": true
    },
    "framework": {
        "className": "<test_class_name>",
        "packageName": "<app_package_name>",
        "testRunner": "<test_runner_class>",
        "testApplicationID": "<test_app_id>",
        "testPackageName": "<test_package_name>",
        "applicationID": "<app_id>",
        "params": {
            "<param_key_1>": "<param_value_1>",
            "<param_key_2>": "<param_value_2>"
        }
    }
}

iOS (XCUITest)

{
    "project": "<project_id>",
    "identifier": "<job_identifier>",
    "desc": "<job_description>",
    "priority": 1,
    "type": "XCUITest",
    "runMode": "distributed",
    "runSetting": "<run_setting_id>",
    "forceDeviceAllocation": false,
    "build": {
        "aut": "<aut_build_id>",
        "test": "<test_build_id>"
    },
    "setting": {
        "performance": {
            "enableAppVitals": true
        },
        "job": {
            "addMoreDevices": false,
            "retryOnSameDevice": false
        }
    },
    "devices": {
        "deviceQueries": [
            {
                "minDeviceCount": 1,
                "maxDeviceCount": 20
            }
        ],
        "devicesGroupIDs": ["allEligibleGroups"],
        "ids": ["<device_id_1>"],
        "limitToMaxDevice": true
    },
    "framework": {
        "jobRunner": "<test_runner_name>",
        "runOnlyClasses": "<test_class_name>",
        "ignoreTestCases": "<test_cases_to_exclude>",
        "xcuitestPrepareSource": "RobusTest",
        "xctestplanFile": "<xctestplan_file_id>",
        "maxScreenshots": 100,
        "cleanDevice": [
            "beforeEachTest",
            "afterEachTest"
        ],
        "xcuitest_params": {
            "env_vars": {
                "<env_key_1>": "<env_value_1>",
                "<env_key_2>": "<env_value_2>"
            }
        }
    }
}

Attribute Reference

Top-Level Attributes

forceDeviceAllocation — Detail

When set to true and no free devices are available, the job:

1. Finds all busy devices that match its requirements
2. Sorts them by job priority (lowest priority first)
3. Force-frees them one by one until the quota is met
4. Displaced instances are closed with status code 63

Works in two ways depending on how devices are specified:

Protection rule: A job with forceDeviceAllocation: true cannot have its own devices force-freed by another job — even one that also has the flag set. This prevents priority conflicts.

Things to keep in mind:

• Only use for genuinely high-priority jobs — it forcibly terminates other running sessions
• If the devices you need are held by another forceDeviceAllocation job, preemption will fail
• A job will never force-free a device it already owns
• Check server logs for ForceDeviceAllocation: and ForceFree: entries to trace what happened

Build

Setting

Controls job behaviour and performance data collection.

setting.performance

setting.job

Devices

Controls which devices the job runs on.

deviceQueries Item

Each item in deviceQueries defines a set of conditions and device count requirements. Conditions are evaluated inline — there is no reference to a saved query ID.

conditions Item

Example — target Android 12 devices, minimum 1, maximum 5:

{
  "devices": {
    "deviceQueries": [
      {
        "minDeviceCount": 1,
        "maxDeviceCount": 5,
        "conditions": [
          {
            "attribute": "version",
            "operator": "=",
            "value": "12"
          }
        ]
      }
    ]
  }
}

Framework

Framework-specific configuration passed to the test runner. Attributes vary by platform.

Android (Espresso)

iOS (XCUITest)

framework.xcuitest_params.env_vars

Key-value pairs injected as environment variables into the XCUITest run. Use these to pass environment configuration, region settings, or authentication tokens to your tests.

"xcuitest_params": {
    "env_vars": {
        "environment": "staging",
        "region": "us",
        "user": "premium"
    }
}

Related Documentation

• Hub Job Payload - Job creation API overview
• Device Queries - Creating and managing device query conditions
• Using Device Groups for Job Creation - Device group selection behaviour
• Run Settings - Configuring run settings for a project
• AppVitals Android Metrics - Metrics collected when enableAppVitals is enabled
• AppVitals iOS Metrics - iOS metrics collected when enableAppVitals is enabled