docs/api/device_runner_dispatch.md

   1 # CHIP on-device test dispatch
   2
   3 This document expands on and provides design for on-device test dispatch. The
   4 CHIP on-device testing document states that dispatching should involve a HTTPS
   5 based RESTful protocol that could be integrated with CircleCI.
   6
   7 ## Definitions
   8
   9 **Test run**: Tests instantiation on a test host, consisting of host-side test
  10 binaries and test scripts as well as one or more device-side binaries.
  11
  12 **Test host**: A computing execution environment provided for the purposes of
  13 running tests by a party participating in the scheme.
  14
  15 ## Scope
  16
  17 The scope of this proposal is to support running tests against a known set of
  18 canonical devices and platforms for the purposes of developing core common code
  19 in the CHIP project GitHub repository.
  20
  21 This proposal does not preclude a stakeholder running their own tests against
  22 their own hardware or lab in any way they see fit. The goal is merely to provide
  23 a common way for volunteer organizations to register test infrastructure and
  24 dispatch capabilities to be used by the wider CHIP developer community.
  25
  26 Authentication is not considered strictly part of the test dispatch protocol.
  27 However it is mandated that some form of authentication takes place before any
  28 of the test dispatch operations are issued. Throughout this document it is
  29 assumed that proper authentication and authorization is ensured by the server
  30 hosting the test dispatch service.
  31
  32 ## Objectives
  33
  34 -   **Provide a centralized API** for the dispatching of tests against
  35     potentially distributed lab infrastructure, which CI systems (i.e. CircleCI)
  36     or individual developers may not be directly configured to access.
  37 -   **Decouple test execution from the CI environment**, especially for tests
  38     requiring complex setups, such as radio traffic capture.
  39 -   **Enable** common adoption of **aligned methodologies** for both
  40     certification-style tests and development-support tests (pre/post-submit
  41     testing in pull requests).
  42
  43 ### Certification or pre-certification tests
  44
  45 Certification tests are required to have canonical test suite names.
  46
  47 Here the host side test binaries and scripts are fixed and the device-side
  48 binary can vary by device type. The objective of certification testing is to run
  49 a known fixed set of tests against new and existing devices. Dispatching of
  50 certification tests involves specifying the canonical test suite name and
  51 providing the requisite arguments, such as device-side binary and device type.
  52
  53 ### Development support tests
  54
  55 Development support test suites are required to have canonical names, but they
  56 may, during execution, check-out the actual test script from a given PR, or from
  57 the artifacts uploaded for the test job.
  58
  59 The test is executed against a pull request and may target many device types.
  60 Therefore, both host-side and device-side artifacts may vary and have to be
  61 uploaded in the respective argument to test dispatch operation. Dispatching of
  62 development support test suites therefore involves specifying a canonical test
  63 suite name, the PR URL, pre-built artifacts (host side and device-side) and
  64 optional test-specific arguments.
  65
  66 ### Common constraints for dispatch
  67
  68 In order to support running tests, some common arguments are required to
  69 determine during dispatch whether a given combination of targets can be
  70 supported.
  71
  72 These constraints include:
  73
  74 -   A canonical device type list to determine whether a target runner has all
  75     the targets needed. (Note that new hardware developers may provide a
  76     non-canonical device type for running their own certification on their own
  77     lab. Canonical device types exist for development support tests.)
  78 -   An optional node ID (unique UUID) to force execution on a given registered
  79     infrastructure for test purposes.
  80
  81 Example of canonical test suite names:
  82
  83 -   RendezVousTest: loads binaries on HW, validates that assumptions about
  84     RendezVous advertising payload are still valid.
  85 -   BasicCHIPRegression: loads binaries on HW, validates against regressions on
  86     multiple axes of the test. Potentially runs updated tests scripts from the
  87     PR itself.
  88
  89 ## Aggregator Dispatch Interface API
  90
  91 We conceptualize an aggregator service where all the tests are sent to be
  92 further dispatched to or pulled by participating infrastructure/lab providers.
  93
  94 For the prototype phase the aggregator may be the same service that runs tests
  95 as well, i.e. further dispatch/pull/registration may not happen in the
  96 prototype.
  97
  98 This is the API which CircleCI and individual test developers can use. There may
  99 be other APIs (e.g. administrator API) to the aggregator that provide richer
 100 functionality. For now we don't discuss those. The API for communication between
 101 the aggregator and test labs is to be specified at a later time.
 102
 103 The goal of decoupling dispatch from execution is to avoid coupling running the
 104 tests to a given lab’s or organization’s infrastructure. The dispatch interface
 105 API provides a separation of concerns of “what to run”/“what happened” versus
 106 “how to run”/“where to run”.
 107
 108 ### Resources and operations
 109
 110 /available_test_suites - Collection resource, all the canonical test suite
 111 names.
 112
 113 -   GET gets the list of known canonical test suite names
 114
 115 /dispatch - Collection resource, all the currently running test executions.
 116
 117 -   POST dispatches a new test, returning its URI with the test run identifier
 118     'job_id'. - Arguments - Canonical Test Suite name e.g.
 119     "CHIP_basic_test_suite" - ZIP file upload of artifacts (device-side and, if
 120     needed, host-side) - Some common required inputs (see section below) -
 121     Test-suite-specific configuration/contents may also be provided for the test
 122     suite executor to use. - Maximum time the client is willing to wait for
 123     results (seconds) - In case of execution timed out, the test job would be
 124     considered FAILED, due to time-out. - Maximum time the client is willing to
 125     wait for test to start (seconds) - In case of time-out to dispatch, the test
 126     job would be considered ABORTED in the results as opposed to FAILED -
 127     Authentication requirements may cause a given requestor to be throttled by
 128     internal logic.
 129
 130 /status/<job_id> - Member resource, an individual test.
 131
 132 -   GET returns the status of the test: scheduled, running, finished, aborted.
 133 -   DELETE cancels the test.
 134
 135 /status/<job_id>/results - Collection resource, all the files resulting from the
 136 test run.
 137
 138 -   GET returns the list of (file_name, file_id) pairs.
 139     -   Only mandatory file:
 140         -   test_suite_results.json
 141             -   Normalized test results, see section below.
 142
 143 /status/<job_id>/results/<file_id> - Member resource, and individual result
 144 file.
 145
 146 -   GET returns the contents of the file.
 147
 148 ### /dispatch arguments
 149
 150 **test_suite_name**: _Required_. Name of the test suite.
 151
 152 **host_artifacts**: _Only required for development support tests_. A file (most
 153 likely a ZIP file) corresponding to all the scripts and binaries to be run by
 154 the test host. The test host must be able to unzip, recognize and execute
 155 contents.
 156
 157 **device_artifacts**: _Required_. A file (most likely a ZIP file) corresponding
 158 to all the binaries to be flashed on the device. The test host must be able to
 159 unzip, recognize and flash contents.
 160
 161 **timeout_for_results_seconds**: _Required_. The maximum amount of time in
 162 seconds the client is willing to wait for results. After this much time the test
 163 can be killed by the test host.
 164
 165 **timeout_for_start_seconds**: _Required_. The maximum amount of time in seconds
 166 the client is willing to wait for the test to start. If after dispatch the test
 167 does not start after this much time the test can be descheduled by the
 168 aggregator.
 169
 170 ### test_suite_results.json contents
 171
 172 TBD.
 173
 174 ### Aggregator-to-lab dispatch API
 175
 176 TBD.
 177
 178 ### Lab Registration Interface API
 179
 180 Once agreement on the dispatch API is cemented, the API to register a given
 181 executor with certain tests and devices capabilities can be defined.
 182
 183 TBD.