Test API

Status: moving to kernelci.org/docs

---

Test results submission via test API

This page describes how to utilise test API to submit test results.

This API is meant to be used by non-LAVA labs only. In case you want to submit LAVA test results, you should utilise the callback API

Test API is the REST API available at /group/test or /test endpoint. This API is meant to be used by non-lava labs to submit the test results to KernelCI. At the moment it supports the POST method to push the results. Other HTTP methods are not supported.

Test API usage needs authorstation, therefore each request needs to provide an authentication token in the Authorization HTTP header.

e.g.

Authorization: 92dbb3f6-32f5-4242-b51a-830e2ad2f443

Each test API request needs to contain JSON content that defines a test group and test cases within it. It's possible to provide nested structures, in such case sub_groups field should be used to provide a list of test group JSON objects.

Test Cases

Test cases should be defined in a form of a list of test_case JSON objects and put as a value of the test_cases key.

Current schema of a test_group object may be found at https://api.kernelci.org/schema-test-case.html#schema-test-case-post

Subgroups

Subgroups have the same structure as described in this document and should be provided as a value of the sub_groups key in a form of the list of test_group object.

Current schema of a test_group object may be found at https://api.kernelci.org/schema-test-group.html#schema-test-group

Logs

It's possible to attach test log information in a form of a string put as a value of the log key.

At the moment logs are not processed by the KernelCI. They're simply stored as a text file.

Mandatory fields

There is some information which is mandatory for every test_group object. Mandatory fields are:

• kernel - The name of the kernel or the git describe value
• name - The name given to this test group
• build_environment - "Build environment name as used in the build configuration e.g. gcc-8
• defconfig - The name of the defconfig
• lab_name - The name of the lab executing this test group
• job - The name of the job (aka the git tree)
• git_branch - The branch used for testing
• arch - The architecture type of the board used for testing

Example

Below you may find an example of a curl call that submits a test group with several test cases.

curl -X POST  https://api.kernelci.org/test \
     -H 'Content-Type: application/json' \
     -H 'Authorization: MY_API_TOKEN' \
     -d @- <<'EOF'
     {
        "sub_groups": [],
        "board": "fake-board",
        "build_environment": "gcc-8",
        "git_commit": "42a5a774ef093e1ebbe4df290405900c7debe7af",
        "name": "Fake-test-group-with-test-cases-01",
        "metadata": {},
        "initrd_info": null,
        "git_branch": "mgalka",
        "version": "1.0",
        "mach": null,
        "board_instance": null,
        "job": "kernelci-local-snapshot-032",
        "file_server_resource": null,
        "initrd": null,
        "device_type": "fake-device-type",
        "arch": "x86_64",
        "kernel" : "kernelci-local-snapshot-032",
        "definition_uri": null,
        "defconfig": "x86_64_defconfig",
        "defconfig_full": "x86_64_defconfig",
        "image_type": null,
        "lab_name": "lab-mgalka",
        "index": 999,
        "job_id": null,
        "endian": null,
        "test_cases": [{"name": "FAKE_VIDIOC_QUERYCAP", 
                        "time": 1.0, 
                        "samples_sum": null,
                        "maximum": null,
                        "samples": null,
                        "attachments": [],
                        "minimum": null,
                        "vcs_commit": null,
                        "test_group_name": null,
                        "kvm_guest": null,
                        "version": "1.1",
                        "definition_uri": null,
                        "measurements": [],
                        "metadata": null,
                        "parameters": {},
                        "samples_sqr_sum": null,
                        "status": "PASS"}, 
                        {"name": "FAKE_MC-information-see-Media-Driver-Info-above",
                         "time": 1.0,
                         "samples_sum": null,
                         "maximum": null,
                         "samples": null,
                         "attachments": [],
                         "minimum": null,
                         "vcs_commit": null,
                         "test_group_name": null,
                         "kvm_guest": null,
                         "version": "1.1",
                         "definition_uri": null,
                         "measurements": [],
                         "metadata": null,
                         "parameters": {},
                         "samples_sqr_sum": null,
                         "status": "PASS"}, 
                         {"name": "USERPTR-select",
                          "time": 1.0,
                          "samples_sum": null,
                          "maximum": null,
                          "samples": null,
                          "attachments": [],
                          "minimum": null,
                          "vcs_commit": null,
                          "test_group_name": null,
                          "kvm_guest": null,
                          "version": "1.1", 
                          "definition_uri": null,
                          "measurements": [],
                          "metadata": null,
                          "parameters": {},
                          "samples_sqr_sum": null,
                          "status": "FAIL"}],
        "time": 1.0,
        "log": "Fake LOG\nJust some text\nNo parsing"
    } 
EOF