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