Job Payload API Reference

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.

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 attributes for job creation:

Build Configuration

The build section specifies the application and test files to be used:

Device Configuration

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

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

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",
  "attributes": {
    "COUNTRY": "US",
    "ENV": "staging",
    "BUILD_NUMBER": "1.2.3"
  },
  "build": {
    "aut": "67bd4baa0bc67b454f32b054",
    "test": "67bd4bd30bc67b454f32b055"
  },
  "devices": {
    "deviceQueries": [
      {
        "conditions": [
          {"attribute": "osVersion", "value": "11.0"},
          {"attribute": "manufacturer", "value": "Samsung"}
        ],
        "minDeviceCount": 2,
        "maxDeviceCount": 5
      }
    ],
    "devicesGroupIDs": ["60a1b2c3d4e5f6789012345"]
  }
}

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
• Reading Job Reports - Understanding test reports and analytics