Share this page

# Add automated test results

This topic describes how to add automated test results using the REST API.

In this topic:

## Flow

To send test results to the OpenText Software Delivery Management server from other applications:

1. Authenticate and sign in.

2. Retrieve the XSD schema of the payload containing the test results.

3. Verify that the payload conforms to the XSD schema before pushing the test results.

4. Push the test results using test-results.

5. Check the status of the POST.

Use this topic as a procedural guide. For full endpoint contracts, payload structures, and field-level rules, see Automated test results API reference.

## Retrieve the test results payload

Before pushing the test results, retrieve the XSD schema of the payload using a GET operation:

`GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results/xsd`

Use the XSD schema to prepare and validate your payload before using it. The XSD endpoint is the authoritative contract for payload validation.

## Validate the test results payload

Validate your XML against the XSD before sending the POST. For payload structure details and sample payloads, see Payload definition and Sample payloads.

Link tests and test run to other entities in the payload

The following table describes the XML elements to use in the payload to link to each entity type. To link to an entity or attribute from a test or test run, use the REST entity name or the element or attribute in the payload XML.

Entity | Entity name in REST | Element / attribute in payload XML
--- | --- | ---
Release | release | release or release_ref
Story or Feature | story or feature | backlog_items or backlog_item_ref
Application module | product_area | product_areas or product_area_ref
Test | test | test_fields or test_field or test_field_ref
Environment | taxonomy_node | environment or taxonomy or taxonomy_ref
Automated run | run_automated | test_runs or test_run
Build | ci_build | build_name
CI server | ci_server | server_id
Build job | ci_job | job_name
Quality story | quality_story | quality_stories, quality_story_ref
Covered test | test | covered_tests, covered_test_ref
Covered requirement | requirement | covered_requirement, covered_requirement_ref
User tag | user_tag | user_tags, user_tag_ref, user_tag (by value)
Run fields | — | run_fields (run_by / run_by_ref, sprint_ref, environment_ref, quality_stories, user_tags)
Automated test UDF field | — | automated_test_udf_fields
Automated run UDF field | — | automated_run_udf_fields

Note:

- Non-shared UDFs are not supported through the space-level internal API.

- Default CI Plugin payloads do not include the following fields by default: Quality stories, covered tests, covered requirements, user tags, run fields, or UDFs. This is a plugin default, not an API limitation. You can customize the payload to include these fields when sending through the space-level internal API.

### Report the tests and test runs

Verify that the payload is defined according to these guidelines.

- Use the test_runs element to wrap the tests you are reporting.

- Each child test_run element represents a single test run.

- Do not include multiple test_run elements that refer to the same test (for example, elements with the same values for application module and package).

- The maximum number of test runs per request is controlled by server configuration.

For element-level details, see test_runs element and test_run element.

### Set test characteristics and global report context

If the set of tests included in the report share the same characteristics and context, you can specify them globally for all the tests in the report.

- Set characteristics

  For details, see Test characteristics.

- Set context

  You can specify the product / project context of a test by associating it with application modules, requirements, or both. For details, see Linking tests and test run to other entities.

- Set test execution context

  You can specify the context of a test run by associating it with a release, a build, a pipeline, and environment information. For details, see Link to suite and suite run.

### Set test characteristics and individual report context

If the test report contains tests with different characteristics or context, you can specify it per test. To do this, use the same elements as you would use for setting the context per report.

### Set UDF values for tests and runs

Use automated_test_udf_fields and automated_run_udf_fields containers in global context and/or in each test_run.

Before building the payload, always retrieve the runtime XSD from /test-results/xsd and validate against it. UDF field names and allowed shapes are defined by current metadata and permissions.

In pipeline scenarios that inject through a space-level internal resource, custom payloads can include UDFs, but only shared UDFs are supported.

For UDF value formats and examples, see User-defined fields (UDF) injection.

### Resolve conflicts

Context elements might be set both per report and per test, causing conflicts. To handle these conflicts, see Resolving link conflicts.

## POST the test results

Set the Content-Type header field set to application/xml. Make sure that the XML payload containing the test results conforms to the XSD schema as described above.

`POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results`

By default, errors that occur while processing the request are not ignored, and the asynchronous task can end with a failed status. To continue processing valid items when recoverable errors occur, specify the skip-errors parameter:

`POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results?skip-errors=true`

For details on this parameter, see skip-errors.

### Implement polling for asynchronous processing

The POST operation is asynchronous. After POST returns a task ID, poll the task endpoint until the status is terminal (success, warning, failed, or error).

    # Bash example
    BASE_URL="https://<host>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results"
    TASK_ID="1206"

    while true; do
        RESPONSE=$(curl -s -H "Accept: application/json" "$BASE_URL/$TASK_ID")
        STATUS=$(echo "$RESPONSE" | sed -n 's/.*"status"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')

        case "$STATUS" in
            success|warning|failed|error)
                echo "Final status: $STATUS"
                break
                ;;
            queued|running)
                sleep 2
                ;;
            *)
                echo "Unexpected status: $STATUS"
                break
                ;;
        esac
    done

    # Optional: download processing log
    curl -s "$BASE_URL/$TASK_ID/log"

    # Python example
    import time
    import requests

    base_url = "https://<host>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results"
    task_id = "1206"
    terminal = {"success", "warning", "failed", "error"}

    while True:
            r = requests.get(f"{base_url}/{task_id}", headers={"Accept": "application/json"}, timeout=30)
            r.raise_for_status()
            status = r.json().get("status")
            if status in terminal:
                    print("Final status:", status)
                    break
            time.sleep(2)

    log_response = requests.get(f"{base_url}/{task_id}/log", timeout=30)
    print(log_response.text)

Note: You can also use the POST request to update test run results. To update test run results, send another POST request with a unique module, package, class, and name. If a matching test run exists, its data is updated (such as status, starting time, and duration) and new test run results are not created.

## Check status and results

- Check for errors that may have occurred. For details, see Response.

  If errors mention UDF limits, reduce number of unique UDF field names in the payload or split injection into smaller batches.

  If errors indicate unknown or missing fields, verify that the API caller role can view those fields and that they are exposed in the runtime XSD.

- Check return status.

  To see the status of request #1206:

  `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results/1206`

  Response:

      {

      "id": "1206"

      "status": "failed"

      "until": "2016-05-18T05:33:53+0000"

      }

  To see the log of request, use ID from the response of the POST of the test-results (see above).

  `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test-results/1206/log`

  Sample response:

      status: failed

      until: 2016-05-18T08:33:53+0300

      Build reference {server: uuid; build_type: junit-job; build_sid: 1} not resolved

  For details, see Get task status.

- Check if the new automated tests and their run results exist in OpenText Software Delivery Management.

- If UDF fields are rejected as unknown or missing, retrieve the XSD again and verify that the UDF exists in the target workspace and is visible to the API caller.

  Inspect the task log endpoint for the specific failure details before resubmitting the payload.

## See also

- Automated test results API reference
- API access
- Add automated tests
- Run automated tests
- Test results XML sample

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: