Megatest Web App API Specificiation
===================================
Matt Welland <matt@kiatoa.com>
v1.0, 2013-12
Megatest Web App
. See runs
. Manage jobs
. Debug
:numbered!:
[abstract]
Example Abstract
----------------
The Megatest Web App aims to make as much of the power of the dashboard available to the web based user.
:numbered:
// This file is part of Megatest.
//
// Megatest is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Megatest is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Megatest. If not, see <http://www.gnu.org/licenses/>.
Common
------
This is an example endpoint. You will need to use your own cgi server to serve out your megatest runs.
Endpoint: http://kiatoa.com/cgi-bin/megatest
Error format response
~~~~~~~~~~~~~~~~~~~~~
All API errors are returned in the following format:
===================
{ "[blue]#error#" : "[red]#Error message#" }
===================
Get List of Runs
~~~~~~~~~~~~~~~~
URL: <base>/runs
Method: GET
Filter Params: target, testpatt, offset, limit
Megatest Cmd: megatest -start-dir <path to megatest area> -list-runs % -target % -dumpmode json -fields runs:runname,id+tests:state,status:id
Response:
==================
[
{
"[red]#run_id#" : "1",
"[red]#name#" : "runname1",
"[red]#target#" : "target1",
"[red]#tests#" :
[
"[green]#test#":
[
{"[blue]#id#": 1, "[blue]#name#":test1, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target1/runname1/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS#"}
{"[blue]#id#": 2, "[blue]#name#":test2, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target1/runname1/test2", "[blue]#final_logf#": "megatest-rollup-test2.html", "[blue]#status#": "PASS"}
{"[blue]#id#": 3, "[blue]#name#":test3, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target1/runname1/test3", "[blue]#final_logf#": "megatest-rollup-test3.html", "[blue]#status#": "PASS"}
]
]
},
{
"[red]#run_id#" : "2",
"[red]#name#" : "runname2",
"[red]#target#" : "target2",
"[red]#tests#" :
[
"[green]#test#:
[
{"[blue]#id#": 4, "[blue]#name#":[blue]#test1#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
{"[blue]#id#": 5, "[blue]#name#":[blue]#test2#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test2", "[blue]#final_logf#": "megatest-rollup-test2.html", "[blue]#status#": "FAIL"}
{"[blue]#id#": 6, "[blue]#name#":test3, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test3", "[blue]#final_logf#": "megatest-rollup-test3.html", "[blue]#status#": "PASS"}
]
]
}
]
==================
Trigger a new Run
~~~~~~~~~~~~~~~~~~
URL: <base>/runs
Method: POST
Megatest Cmd: megatest -runtests % -target <target> :runname <run_name> -run
Request Params:
==================
{"[blue]#target#": "target_value", "[blue]#runname#" : "runname", "[blue]#test_pattern#": "optional test pattern"}
==================
Response:
If Error
===================
{ "[blue]#error#" : "[red]#Error message#" }
===================
If Success returns the results of the run
==================
[
{
"[red]#run_id#" : "2",
"[red]#name#" : "runname2",
"[red]#target#" : "target2",
"[red]#tests#" :
[
"[green]#test#:
[
{"[blue]#id#": 4, "[blue]#name#":[blue]#test1#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
{"[blue]#id#": 5, "[blue]#name#":[blue]#test2#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test2", "[blue]#final_logf#": "megatest-rollup-test2.html", "[blue]#status#": "FAIL"}
{"[blue]#id#": 6, "[blue]#name#":test3, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test3", "[blue]#final_logf#": "megatest-rollup-test3.html", "[blue]#status#": "PASS"}
]
]
}
]
==================
Get perticular Run
~~~~~~~~~~~~~~~~~~~
URL: <base>/runs/:id
Method: GET
Filter Params: testpatt
Megatest Cmd: megatest -start-dir <path to megatest area> -list-runs <runname> -target % -dumpmode json -fields runs:runname,id+tests:state,status:id
Response:
==================
[
{
"[red]#run_id#" : "2",
"[red]#name#" : "runname2",
"[red]#target#" : "target2",
"[red]#tests#" :
[
"[green]#test#":
[
{"[blue]#id#": 4, "[blue]#name#":[blue]#test1#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
{"[blue]#id#": 5, "[blue]#name#":[blue]#test2#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test2", "[blue]#final_logf#": "megatest-rollup-test2.html", "[blue]#status#": "FAIL"}
{"[blue]#id#": 6, "[blue]#name#":test3, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test3", "[blue]#final_logf#": "megatest-rollup-test3.html", "[blue]#status#": "PASS"}
]
]
}
]
==================
Re-execute a run
~~~~~~~~~~~~~~~~~
URL: <base>/runs/:id
Method: PUT/PATCH
Request Params: {"testpatt" : "pattern"}
Response:
==================
[
{
"[red]#run_id#" : "2",
"[red]#name#" : "runname2",
"[red]#target#" : "target2",
"[red]#tests#" :
[
"[green]#test#":
[
{"[blue]#id#": 4, "[blue]#name#":[blue]#test1#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
{"[blue]#id#": 5, "[blue]#name#":[blue]#test2#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test2", "[blue]#final_logf#": "megatest-rollup-test2.html", "[blue]#status#": "FAIL"}
{"[blue]#id#": 6, "[blue]#name#":test3, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test3", "[blue]#final_logf#": "megatest-rollup-test3.html", "[blue]#status#": "PASS"}
]
]
}
]
==================
Get List of tests within a run
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
URL: <base>/runs/:id/tests
Method: GET
Megatest Cmd: megatest -start-dir <path to megatest area> -list-runs <runname> -target % -dumpmode json -fields runs:runname,id+tests:state,status:id
Response:
==================
[
"[red]#tests#" :
[
{"[blue]#id#": 4, "[blue]#name#":[blue]#test1#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
{"[blue]#id#": 5, "[blue]#name#":[blue]#test2#, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test2", "[blue]#final_logf#": "megatest-rollup-test2.html", "[blue]#status#": "FAIL"}
{"[blue]#id#": 6, "[blue]#name#":test3, "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test3", "[blue]#final_logf#": "megatest-rollup-test3.html", "[blue]#status#": "PASS"}
]
]
==================
Re-execute a test within a run
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
URL: <base>/runs/:id/tests/:id
Method: PUT/PATCH
Response:
==================
{"[blue]#id#": "4", "[blue]#name#":"test1", "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
==================
Get perticular test that belongs to a Runs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
URL: <base>/runs/:id/tests/:id
Method: GET
Megatest Cmd: megatest -start-dir <path to megatest area> -list-runs <runname> -target % -testpattern <pattern> -dumpmode json -fields runs:runname,id+tests:state,status:id
Response:
==================
{"[blue]#id#": "4", "[blue]#name#":"test1", "[blue]#item_path#": "", "[blue]#shortdir#": "/temp/foo/bar/target2/runname2/test1", "[blue]#final_logf#": "megatest-rollup-test1.html", "[blue]#status#": "PASS"}
==================
Notes
-----
Misc ...
1. blah
2. baz