Skip to content

hubjobpayload.rst

Latest commit

 

History

History
377 lines (281 loc) · 11.7 KB

hubjobpayload.rst

File metadata and controls

377 lines (281 loc) · 11.7 KB

Job Payload API Reference

In this section

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, and Appium frameworks
  • Priority Management: Control job execution priority and retry behavior

API Endpoint:

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

For complete API documentation, visit: RobusTest API Documentation

Core Job Attributes

The following table describes the essential attributes for job creation:

Job Payload Attributes
Attribute Name Description Usage Example Type Mandatory
project Project ID of the project in which you are executing the job. Alphanumerical string obtained from Project Home page URL. "project": "<Project ID>" "project": "63bc5697baec733123456820" String Yes
type Type of job being executed (testing framework being used). "type": "<Type of the Job>" "type": "Espresso" String (Espresso, XCUITest, appium) Yes
identifier Custom alphanumeric string to identify a job. Can be viewed in deployment → jobs section and project jobs section. "identifier": "<Job Identifier>" "identifier": "Smoke testing- payment module" String No
desc Brief description of the job. Can include alphanumeric characters and special characters. "desc": "<Description of the Job>" "desc": "Testing Security Token for Triggers" String No
priority Priority of job execution. Higher value = higher priority, lower value = lower priority. "priority": <Job Priority> "priority": 10 Number No
runMode Specifies the order/method in which tests should be executed. "runMode": "<Enter runMode>" "runMode": "distributed" String (parallel, distributed) Yes
jobCategories Helps classify jobs with tags/categories for job analysis. "jobCategories": ["category1","category2"] "jobCategories": ["Functional","smoke","iOS"] Array of Strings No
maxJobAttempts Number of times a job can retry execution if sent back to queue. "maxJobAttempts": <Enter job attempts> "maxJobAttempts": 2 Number No
runSetting Run Setting ID that can be updated in Project → Run Settings page. Includes notifications, timeouts, integrations, etc. "runSetting": "<run setting>" "runSetting": "64745b50baec73ad0214dc53" String No
jobScope Job visibility setting for team collaboration. "jobScope": "<scope>" "jobScope": "public" String No
attributes Custom key-value attributes for job metadata. "attributes": {"key": "value"} "attributes": {"COUNTRY":"in", "ENV":"prod"} Object No

Build Configuration

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

Build Attributes
Attribute Name Description Usage Example Mandatory
build.aut The AUT (Application Under Test) is the test app that needs to be tested. View AUT ID on Project Home Page. "aut": "<AUT ID>" "aut": "67bd4baa0bc67b454f32b054" Yes
build.test APK or ZIP file containing the test cases. View Test Build ID on Project Home Page. "test": "<test ID>" "test": "67bd4baa0bc67b454f32b054" Yes

Device Configuration

Configure device selection and targeting for your test execution:

Device Configuration Attributes
Attribute Name Description Usage Example Mandatory
deviceQueries Device filters and selection criteria for test execution. "deviceQueries": [<device criteria>] "deviceQueries": [{"osVersion": "10.0", "deviceType": "phone"}] Yes
deviceGroupsIDs Array of device group IDs to specify which device groups to use for test execution. "deviceGroupsIDs": ["<group_id>"] "deviceGroupsIDs": ["60a1b2c3d4e5f6789012345"] No
minDeviceCount Minimum number of devices required to run the job. "minDeviceCount": <number> "minDeviceCount": 2 No
maxDeviceCount Maximum number of devices to use for test execution. "maxDeviceCount": <number> "maxDeviceCount": 5 No

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

deviceGroupsIDs Attribute Options:

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

    {
  "deviceGroupsIDs": ["60a1b2c3d4e5f6789012345", "60a1b2c3d4e5f6789012346"]
}

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

  2. Any Available Group: Array with "any" value

    {
  "deviceGroupsIDs": ["any"]
}

    This directs the system to pick devices from any group that the project is part of.

  3. No Group Restriction: Empty array

    {
  "deviceGroupsIDs": []
}

    This directs the system to pick any eligible and available device, regardless of group membership.

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"
  },
  "deviceQueries": [
    {
      "osVersion": "11.0",
      "deviceType": "phone",
      "manufacturer": "Samsung"
    }
  ],
  "deviceGroupsIDs": ["60a1b2c3d4e5f6789012345"],
  "minDeviceCount": 2,
  "maxDeviceCount": 5
}

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
  • Ensure your test bundle is properly zipped and uploaded
  • Include appropriate iOS version targeting in device queries

Appium Jobs:

  • Use "type": "appium" for cross-platform Appium tests
  • Configure device queries for both Android and iOS as needed
  • Consider parallel execution for cross-platform testing

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 job ID:

GET /v3/report/<job_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
.. seealso::

   **Related Topics:**

   * :doc:`hubappium_master` - Appium Hub integration
   * :doc:`hubespresso` - Espresso Hub integration
   * :doc:`hubxcuitest` - XCUITest Hub integration
   * :doc:`continuousintegration` - CI/CD integration strategies
   * :doc:`automationreports` - Understanding test reports and analytics