Project

General

Profile

proposals.txt

first-proposal - szarate, 2018-01-26 17:31

 
1
* Client
2

    
3
How to invoke the client:
4
client <entry_point> <action> <OPTIONS>
5

    
6

    
7
Client options
8

    
9
** Available entry point:
10
- test
11
- worker
12
- group
13
- build
14

    
15
*** Feature table
16

    
17
| entry point | actions     | descriptions                                                                                        |
18
|-------------+-------------+-----------------------------------------------------------------------------------------------------|
19
| test        | restart     | restarts a test. Restarts the parent if the parent status is not success, or if explicity requested |
20
|             | stop/cancel | stop/cancel tests that match certain conditions                                                     |
21
|             | clone       | clone a test from a host to another host.                                                           |
22
|             | status      | returns the status of a test (run, failed, softfailed, canceled)                                    |
23
|             | search      | search for tests according to the inputs                                                            |
24
|             | info        | display several information regarding a test (details, settings, comments, previous results...)     |
25
|-------------+-------------+-----------------------------------------------------------------------------------------------------|
26
| worker      | search      | search for workers according to the inputs                                                          |
27
|             | info        | display several information regarding a worker (host, instance, properties, status...)              |
28
|-------------+-------------+-----------------------------------------------------------------------------------------------------|
29
| group       | search      | search for groups according to the inputs                                                           |
30
|             | info        | display several information regarding a group  (name, tests, prio, arch, latest build results)      |
31
|-------------+-------------+-----------------------------------------------------------------------------------------------------|
32
| build       | search      | search for builds according to the inputs                                                           |
33
|             | info        | display build information (flavor, tests, archs, status)                                            |
34
|             | restart     | restart tests that belongs to a build that match certain conditions                                 |
35
|             | new         | create a new build according to the parameters passed (equivalent to the current "isos post")       |
36
|-------------+-------------+-----------------------------------------------------------------------------------------------------|
37

    
38
*** Explanation
39

    
40
- test
41
  one run of individual test cases
42
  Example of a test screen: https://openqa.suse.de/tests/1412943
43
- worker
44
  Test worker that will run the test
45
  Example of a worker screen: https://openqa.suse.de/admin/workers/936
46
- group
47
  a group of builds
48
  Example of a group screen: https://openqa.suse.de/group_overview/110
49
- build
50
  a group of tests
51
  Example of a build screen: https://openqa.suse.de/tests/overview?distri=sle&version=15&build=422.1&groupid=110
52

    
53
**** units
54
1. group > build > test
55
A group is a bunch of builds.
56
A build is a bunch of tests
57

    
58
2.
59
Worker
60

    
61
** Assumptions
62
1. The command line options, will have precedence over the options passed over the options file. This means that the options in the options file will not override the options passed via switches in the command line.
63
2. All the commands need to support a --json-data <file.json> which will be the equivalent of invoking the action with flags/switches.
64
3. The default server where the user can do operation is the current host
65
4. The api key and the api scret can be be specifed on the client.conf file
66

    
67
** Examples
68
*** test
69
- restart
70
  restart a test, including the parent
71

    
72
Invocations
73
$ client test restart --id <ID>
74
$ client test restart --id <ID> --from <REMOTE_HOST>
75
$ client test restart --id <ID>
76
$ client test restart --id <ID> --vars ISO=
77

    
78
possible returns:
79
{"invocation":{"status":0, "message":"ok"}, "returns": [<new_ID>]}
80
{"invocation":{"status":0, "message":"ok"}, "returns": [<parent_ID>, <new_ID>]}
81
{"invocation":{"status":1, "message":"unknown remote host"}}
82
{"invocation":{"status":2, "message":"unknown test"}}
83

    
84
- stop
85
  stop a test
86

    
87
Invocations
88
$ client test stop --id <ID>
89
$ client test stop --id <ID> --from <REMOTE_HOST>
90

    
91
possible returns:
92
{"invocation":{"status":0, "message":"ok"}}
93
{"invocation":{"status":1, "message":"unknown remote host"}}
94
{"invocation":{"status":2, "message":"unknown test"}}
95

    
96
- clone
97
  clone a test
98

    
99
Invocations
100
$ client test clone --id <ID> 
101
$ client test clone --id <ID> --from <remote_host>
102
$ client test clone --id <ID> --from <remote_host> --to <destination_host> --vars ISO=
103

    
104
possible returns:
105
{"invocation":{"status":0, "message":"ok"}, "returns":{"id": <NEW_ID>}}
106
{"invocation":{"status":1, "message":"unknown remote host"}}
107
{"invocation":{"status":2, "message":"unknown test"}}
108
{"invocation":{"status":3, "message":"ambigous options"}}
109

    
110
- status
111
  return the status of the test
112

    
113
Invocations:
114
$ client test status --id <ID>
115
$ client test status --id <ID> --from <remote_host>
116

    
117
possible returns:
118
{"invocation":{"status":0, "message":"ok"}, "returns": "failed"}
119
{"invocation":{"status":0, "message":"ok"}, "returns": "softfailed"}
120
{"invocation":{"status":0, "message":"ok"}, "returns": "running"}
121
{"invocation":{"status":0, "message":"ok"}, "returns": "scheduled"}
122
{"invocation":{"status":0, "message":"ok"}, "returns": "passed"}
123
{"invocation":{"status":0, "message":"ok"}, "returns": "skipped"}
124
{"invocation":{"status":1, "message":"unknown remote host"}}
125
{"invocation":{"status":2, "message":"unknown test"}}
126

    
127

    
128
- search
129
  search for tests according to the inputs
130
  _note_: for obvious reasons only the last 500 jobs executed plus the current ones will be searched
131

    
132

    
133
Invocations:
134
$ client test search --result failed
135
The -- flags can be one of the following arch, build, comments, distri, since
136
The since will take either Hours, or Days, and it will return all the tests that were executed since that time.
137

    
138
$ client test  search --result skipped --from <remote_host>
139
$ client test  search --result skipped --from <remote_host> --since 1d
140

    
141
possible returns:
142
{"invocation":{"status":0, "message":"ok"}, "returns": [TEST1,TEST2,TEST3]}
143
{"invocation":{"status":0, "message":"ok"}, "returns": []}
144
{"invocation":{"status":1, "message":"unknown remote host"}}
145
{"invocation":{"status":2, "message":"unknown test"}}
146

    
147
with TEST<X> being a list of ids
148

    
149

    
150
- info
151
  to display several information according to the options passed. 
152

    
153
# TODO: how to get the previous results?
154
# http GET https://openqa.suse.de/api/v1/jobs/1421610
155
# http GET https://openqa.suse.de/api/v1/jobs/1421610/details
156
# http GET https://openqa.suse.de/api/v1/jobs/1421610/comments
157

    
158
client test info --id 123
159
client test info --id 123 --attributes id
160
client test info --id 123 --attributes previous_results --attributes version
161

    
162
possible returns:
163
{"invocation":{"status":0, "message":"ok"}, "returns": {"id":<ID>, "comments":["comment","comment2"]}}
164

    
165

    
166

    
167
*** worker
168
- status
169
  to get the status of a worker
170

    
171
$ client worker status --id 123
172

    
173
possible returns:
174
{"invocation":{"status":0, "message":"ok"}, "returns": "Offline"}
175

    
176
- info
177
  to display several information from the worker according to the options passed
178

    
179
$ client worker info --id 123 --display host --display instance
180

    
181
possible returns:
182
{"invocation":{"status":0, "message":"ok"}, "returns": {"Host":"openqa", "Instance":"1"}}
183

    
184
- search
185
  to get a list of workers
186
The --flags can be one of the following: host, instance, alive, connected, property.
187
The propery flag needs to be in the form of KEY=VAL
188

    
189
$ client worker search --alive yes --status running
190
$ client worker search --alive yes --status running --propery WORKER_CLASS=qemu_x86_64
191

    
192
{"invocation":{"status":0, "message":"ok"}, "returns": [WORKER1]}
193

    
194
With worker 1 containing the following info:
195

    
196
{
197
    "alive": 0, 
198
    "connected": 0, 
199
    "host": "tragicbox", 
200
    "id": 1, 
201
    "instance": 1, 
202
    "properties": {
203
        "CPU_ARCH": "x86_64", 
204
        "CPU_MODELNAME": "Intel(R) Xeon(R) CPU E5-1620 v3 @ 3.50GHz", 
205
        "CPU_OPMODE": "32-bit, 64-bit", 
206
        "INTERACTIVE": "0", 
207
        "ISOTOVIDEO_INTERFACE_VERSION": "", 
208
        "JOBTOKEN": "CEFHLTGGkJgg53b4", 
209
        "MEM_MAX": "15969", 
210
        "STOP_WAITFORNEEDLE": "0", 
211
        "STOP_WAITFORNEEDLE_REQUESTED": "0", 
212
        "VERSION": "", 
213
        "WEBSOCKET_API_VERSION": "", 
214
        "WORKER_CLASS": "qemu_x86_64,qemu_i686,qemu_i586,64bit,svirt-xen,caasp_x86_64,svirt-hyperv", 
215
        "WORKER_TMPDIR": "/tmp/5_kzfD5Uqd"
216
    }, 
217
    "status": "dead", 
218
    "websocket": 0
219
}
220

    
221

    
222
*** group
223
- search
224
  search test groups
225

    
226
$ client group search -name functional
227

    
228
possible returns
229
{
230
  "invocation": {"status": 0, "message": "ok"},
231
  "returns": {"groups": [{"id":ID, "name":"name", "builds":[ID1,ID2]}]}
232
}
233

    
234

    
235
- display
236
  display several information regarding a test group
237

    
238
client group search
239
client group display --id 123 --builds_younger 10d
240

    
241
*** build
242
- restart
243
  Restart tests that match the options
244

    
245
$ client build restart --id 123 --filter name=raid --filter status=failure
246
# restarting tests from a build that match the filter options
247
{
248
  "invocation": {"status": 0, "message": "ok"},
249
  "returns": {"ids":[ID1, ID2, ID3]}
250
}
251

    
252
$ client build restart --id 99999 --name raid
253
# when trying to restart tests of a non existing build
254
{
255
  "invocation": {"status": 0, "message": "no build found"}
256
}
257

    
258
$ client build restart --id ID 
259
# restarts all the tests of this build
260
{
261
  "invocation": {"status": 0, "message": "ok"}
262
}
263

    
264

    
265

    
266
- info
267
  Display the tests and the results of a build.
268

    
269
$ client build info --id 123 --name raid
270
{
271
"invocation": {"status": 0, "message": "ok"},
272
"returns": [
273
  {"name": "RAID0", "tests": [{"arch":"aarch64","id": 1403568, "status": "softfailed"}, {"arch":"ppc64le","id":1403730, "status":"failed", "failure":"first_boot", "bug": "bsc#1065150"}]},
274
  {"name": "RAID1", "tests": [{"arch":"aarch64","id": 1403586, "status": "softfailed"} ]}
275
]
276
}
277

    
278
$ client build info --id 123 --arch x86_64
279
{
280
"invocation": {"status": 0, "message": "ok"},
281
"returns": [
282
  {"name": "RAID0", "tests": [{"arch":"x86_64","id": 1404070, "status": "softfailed"}]},
283
  {"name": "RAID1", "tests": [{"arch":"x86_64","id": 1404101, "status": "softfailed"}]}
284
]
285
}
286

    
287
$ client build info --id 123 --filter status=failed
288

    
289
{
290
"invocation": {"status": 0, "message": "ok"},
291
"returns": [
292
  {"name": "RAID0", "tests": [{"name":"regression test", "arch":"x86_64","id": 1404070, "status": "softfailed"}]}
293
]
294
}
295

    
296

    
297

    
298
- search
299
  search for builds 
300

    
301
$ client build search --groupid <ID> --name <grub2>
302
# Search a build inside a group id
303

    
304
{
305
"invocation": {"status": 0, "message": "ok"},
306
"returns": { "ids": [ID_TEST1, ID_TEST2,....] }
307

    
308
}
309

    
310

    
311
- new
312
  create a new build (equivalent to isos post)
313

    
314
$ client build new --group <ID> --var KEY=VAL
315
{
316
"invocation": {"status": 0, "message": "ok"},
317
"returns": { "ids": [ID_TEST1, ID_TEST2,....] }
318

    
319
}
320

    
321

    
322

    
323
** Return value
324
The client calls should always return a json with the mandatory "invocation" table parameter, containing status and message:
325

    
326
{
327
 "invocation": {
328
   "status": 0,
329
   "message": "ok"
330
   },
331
}
332

    
333
- status
334
  If the invocation was ok (0) or not ok (not zero)
335
- message
336
  Any message regarding the command execution.
337

    
338
Example of invocation that returns a list of some call:
339
{
340
 "invocation": {
341
   "status": 0,
342
   "message": "ok"
343
   },
344
   "returns": {
345
     "key 1": "value 1",
346
     "key 2": "value 2",
347
     "key 3": "value 3"
348
     "key 4": ["1","2","3"]
349
   }
350
}