Job Payload Attribute List

Overview

The Job Payload API allows you to programmatically create and execute automated test jobs on RobusTest Hub. This API is essential for CI/CD integration and enables you to trigger test execution remotely using structured JSON payloads. This page lists every attribute the job payload accepts.

Key Benefits:

• Automated Test Execution: Trigger tests programmatically from your CI/CD pipeline
• Flexible Configuration: Comprehensive job configuration options
• Scalable Testing: Execute tests across multiple devices simultaneously
• Framework Support: Compatible with Espresso, XCUITest, Appium, Selenium, Roku, and Karate API frameworks
• Priority Management: Control job execution priority and retry behavior

API Endpoint:

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

Core Job Attributes

The following table describes the essential top-level attributes for job creation:

runMode — parallel vs distributed

• parallel: Each test case is executed on each device picked up by the job. If a job with 20 test cases runs on 5 devices, all 20 tests run on each of the 5 devices — Test Case 1 starts on Device 1, Device 2, Device 3, etc. simultaneously, and when a test case finishes on a device, the next test case begins on it, until all 20 tests have run on all 5 devices. The goal of parallel execution is device coverage — verifying tests pass across as many device models/OS versions as possible.
• distributed: Test cases are distributed across the available devices rather than repeated on each one. If a job has 20 test cases and 5 devices, Test Case 1 runs on Device 1, Test Case 2 on Device 2, and so on until all 5 devices are busy; once a device finishes its test case, the next queued test case (e.g. Test Case 6) starts on it, and so on until all test cases have run once.

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 Configuration

The build section specifies the application and test files to be used. Builds are uploaded as APKs for Espresso and Appium jobs, and as ZIP files for XCUITest jobs.

"build": {
    "aut": "67bd4baa0bc67b454f32b054",
    "test": "67bd4bd30bc67b454f32c6f0"
}

Setting Configuration

Controls job behaviour and performance data collection, nested under the setting object.

"setting": {
    "performance": {
        "enableAppVitals": true
    },
    "job": {
        "addMoreDevices": false,
        "retryOnSameDevice": false
    }
}

Device Configuration

Configure device selection and targeting for your test execution. Device configuration is nested under the devices object.

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. Jobs begin executing once minDeviceCount is met.

conditions Item

Example — string value, target Android 16 devices:

{
  "attribute": "version",
  "operator": "=",
  "value": "16"
}

Example — array value, in operator:

{
  "attribute": "ssid",
  "operator": "in",
  "value": ["ssid1", "ssid2"]
}

Example — boolean value:

{
  "attribute": "wifi",
  "operator": "=",
  "value": true
}

Full example — target Android 12 devices, minimum 1, maximum 5:

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

Device Groups Configuration

You can use the Device Groups feature to enable selection of devices from specific sets of devices. This provides better control over device allocation and test execution.

Prerequisites:

• At least one device group must be created
• Your project and desired devices must be part of that group

devicesGroupIDs Attribute Options:

1. Specific Group IDs: Array with one or more group IDs

   {
     "devices": {
       "devicesGroupIDs": ["60a1b2c3d4e5f6789012345", "60a1b2c3d4e5f6789012346"]
     }
   }
   

   This directs the system to pick devices only from the specified group(s).

2. All Eligible Groups: Use "allEligibleGroups" to pick devices from all groups the project belongs to

   {
     "devices": {
       "devicesGroupIDs": ["allEligibleGroups"]
     }
   }
   

Framework Configuration

Framework-specific configuration passed to the test runner, nested under the framework object. Attributes vary by platform/testing framework.

Test Selection (Espresso / XCUITest)

Android (Espresso)

"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)

"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>"
        }
    }
}

framework.xcuitest_params.env_vars example:

"xcuitest_params": {
    "env_vars": {
        "environment": "pp",
        "region": "in",
        "tokenLogin": "true"
    }
}

Integrations and Git Hook

The sub-fields inside gitHook.pr and gitHook.commit aren't documented yet.

"gitHook": {
    "pr": {},
    "commit": {}
}

Example Job Payload

Here's a complete example of a job payload for running Espresso tests:

{
  "project": "63bc5697baec733123456820",
  "type": "Espresso",
  "identifier": "Smoke Test - Payment Module",
  "desc": "Automated smoke tests for payment functionality",
  "priority": 10,
  "runMode": "distributed",
  "jobCategories": ["Functional", "Smoke", "Payment"],
  "maxJobAttempts": 3,
  "runSetting": "64745b50baec73ad0214dc53",
  "jobScope": "public",
  "forceDeviceAllocation": false,
  "attributes": {
    "COUNTRY": "US",
    "ENV": "staging",
    "BUILD_NUMBER": "1.2.3"
  },
  "build": {
    "aut": "67bd4baa0bc67b454f32b054",
    "test": "67bd4bd30bc67b454f32b055"
  },
  "setting": {
    "performance": {
      "enableAppVitals": true
    },
    "job": {
      "addMoreDevices": false,
      "retryOnSameDevice": false
    }
  },
  "devices": {
    "deviceQueries": [
      {
        "conditions": [
          {"attribute": "osVersion", "operator": "=", "value": "11.0"},
          {"attribute": "manufacturer", "operator": "=", "value": "Samsung"}
        ],
        "minDeviceCount": 2,
        "maxDeviceCount": 5
      }
    ],
    "devicesGroupIDs": ["60a1b2c3d4e5f6789012345"],
    "limitToMaxDevice": true
  },
  "framework": {
    "className": "com.example.suites.SmokeTestSuite",
    "packageName": "com.example.app",
    "testRunner": "androidx.test.runner.AndroidJUnitRunner",
    "testApplicationID": "com.example.app.test",
    "testPackageName": "com.example.app.test",
    "applicationID": "com.example.app",
    "params": {
      "env": "staging"
    }
  }
}

Framework-Specific Considerations

Espresso Jobs:

• Use "type": "Espresso" for Android Espresso tests
• Ensure your test APK is properly uploaded and referenced in build.test
• Consider using "runMode": "distributed" for faster execution

XCUITest Jobs:

• Use "type": "XCUITest" for iOS XCUITest tests
• Use "type": "XCTest" for XCTest jobs that do not require a separate test build
• Ensure your test bundle is properly zipped and uploaded
• Include appropriate iOS version targeting in device queries

Appium Jobs:

• Use "type": "Appium(App)" for Appium app testing
• Use "type": "Appium(Browser)" for Appium browser testing
• Configure device queries for both Android and iOS as needed
• Consider parallel execution for cross-platform testing

Selenium Jobs:

• Use "type": "Selenium(Web Apps)" for Selenium web application tests

Roku Jobs:

• Use "type": "Roku" for Roku channel tests

Karate API Jobs:

• Use "type": "Karate API" for Karate API tests

Job Execution Workflow

When you submit a job via the API, it follows this workflow:

1. Job Submission: Job is created with the provided payload
2. Validation: Payload is validated for required fields and format
3. Queuing: Job enters the pending state based on priority
4. Device Allocation: System reserves required devices based on criteria
5. Execution: Tests run on allocated devices
6. Reporting: Results are compiled and made available

Job Status Monitoring:

After job submission, you receive a job ID which can be used to monitor execution:

GET /v3/job/<job_id>/status

Report Access:

Access detailed reports using the run ID returned in the job response:

GET /v3/report/<run_id>/<framework_type>

Best Practices

Job Configuration:

• Use Descriptive Identifiers: Choose meaningful job identifiers for easy tracking
• Set Appropriate Priority: Balance job priority with team workflow requirements
• Configure Retry Logic: Set reasonable maxJobAttempts for handling transient failures
• Use Job Categories: Tag jobs with relevant categories for better organization

Device Management:

• Optimize Device Selection: Use specific device queries to target appropriate devices
• Leverage Device Groups: Organize devices into groups for better resource management
• Balance Device Count: Set appropriate min/max device counts based on test requirements

CI/CD Integration:

• Secure API Keys: Keep access keys secure and rotate them regularly
• Handle API Responses: Implement proper error handling for API calls
• Monitor Job Status: Track job execution and handle failures appropriately
• Integrate with Build Pipeline: Trigger jobs based on build events and results

Performance Optimization:

• Use Parallel Execution: Leverage runMode: "parallel" for faster test execution
• Optimize Test Selection: Use targeted test execution when possible
• Monitor Resource Usage: Track device utilization and optimize allocation

Troubleshooting

Common Issues:

• Invalid Project ID: Ensure project ID is correctly obtained from project URL
• Missing Build IDs: Verify AUT and test build IDs are valid and accessible
• Device Allocation Failures: Check device availability and group configurations
• Authentication Errors: Verify access key validity and permissions

Debugging Tips:

• Validate Payload: Use JSON validators to ensure payload structure is correct
• Check Device Status: Verify target devices are available and online
• Monitor Job Logs: Review job execution logs for detailed error information
• Test Configuration: Verify run settings and device queries are properly configured

Related Documentation

• Appium Hub - Appium Hub integration
• Espresso Hub - Espresso Hub integration
• XCUITest Hub - XCUITest Hub integration
• 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
• Reading Job Reports - Understanding test reports and analytics