emender-service

REST API and web-based service to control Emender and to show test results generated by Emender.

Prerequisities

Installation

1. JVM version 6 or better
2. Leiningen
3. GNU Make

For the already compiled service

1. JRE version 6 or better (JRE 7 is recommended)
2. GIT CLI client

Installation

1. Clone the emender-service repository

2. Run the following command:

   $ make all

Usage

To start the service, run the following command:

$ make run

Configuration

All options needs to be provided in the configuration file emender-service.ini

Content of emender-service.ini

The main configuration file is written in so-called INI format. File is divided into several sections, each section contain various pairs key=value. Please don't use quotes for string values, it's not necessary.

[jenkins]
hostname=http://my.jenkins.instance.org
port=8080

[tests]
job-suffix=(test)

[result-cache]
filename=results.edn
pretty-print=true
use-cache=false
 
[api]
prefix=/api/v1

[ui]
mailto=ptisnovs@redhat.com

[emender]
path=/home/user/emender/
tests=/home/user/emender/test/

[config]
verbose=false
delete-workdirs=true

The only section that needs to be changed is [emender]. You need to provide path to Emender itself and to Emender tests directory as well. The section [jenkins] and [tests] is not used at this moment, as it needs much better integration with Jenkins (not needed ATM).

Usage

Emender-service can be controlled via set of simple REST API calls. Every supported API calls are described below:

Get info about Emender service API

Address: http://$hostname:$port/api/info

Method: GET

Example:

$ curl -v localhost:3000/api/info

Return value (example):

{"toasterNotifications":["info|Api response|<strong>Emender Service<\/strong> api v1 on<\/br>$hostname"],"configuration":$configuration}

Get list of all books (ie. already tested books)

Address: http://$hostname:$port/api/v1/books http://$hostname:$port/api/v1/book-list

Method: GET

Example:

$ curl -v localhost:3000/api/v1/books
$ curl -v localhost:3000/api/v1/book-list

Return value (example):

["doc-Other-Book (test)","doc-Red_Hat_Developer_Toolset-1-Release_Notes-en-US (test)"]

Get list of all test jobs

Address: http://$hostname:$port/api/v1/jobs http://$hostname:$port/api/v1/job-list

Method: GET

Example:

$ curl -v localhost:3000/api/v1/jobs
$ curl -v localhost:3000/api/v1/job-list

Return value (example):

[{"id":1,"job":"doc-Red_Hat_Developer_Toolset-1-Release_Notes-en-US (test)"},
 {"id":2,"job":"doc-Other-Book (test)"},
 {"id":3,"job":"doc-Red_Hat_Developer_Toolset-1-Release_Notes-en-US (test)"}]

Get information about given job

Address: http://$hostname:$port/api/v1/job-info/$job-id

Method: GET

Example:

$ curl -v localhost:3000/api/v1/job-info/1

Return value (job number is correct):

{"id":2,"datetime":"2016-04-19 16:16:31","job":"doc-Other-Book (test)","url":null,"branch":null,"results":"actual test results"}

Return value (job number is incorrect):

{"status":"error","error":"Bad job ID","uri":"\/api\/v1\/job-info\/gfdgdfs"}

Send information that test has been started outside the service (in Jenkins for example)

Address: http://$hostname:$port/api/v1/job-started/$book-name

Method: POST

Example:

$ curl -X POST --header "Content-Type: application/json" -v "localhost:3000/api/v1/job-started/doc-Other-Book+(test)"

Return value:

{"status":"ok"}

Send information that test has been finished outside the service (in Jenkins for example)

Address: http://$hostname:$port/api/v1/job-finished/$book-name

Method: POST

Example:

$ curl -X POST --header "Content-Type: application/json" -v "localhost:3000/api/v1/job-finished/doc-Other-Book+(test)"

Return value:

{"status":"ok"}

Send test results for test started outside the service (in Jenkins for example)

Address: localhost:3000/api/v1/job-results/$book-name

Method: POST

Example:

$ curl -X POST --header "Content-Type: application/json" -d "@results.json" -v "localhost:3000/api/v1/job-results/$book-name

The file results.json should be generated by Emender, ie. it must use its format.

Return value:

{"status":"ok"}

Send test results including HTML page for test started outside the service (in Jenkins for example)

Address: localhost:3000/api/v1/job-results-html/$book-name

Method: POST

Example:

$ curl -X POST --header "Content-Type: text/plain" -d "@results.txt" -v "localhost:3000/api/v1/job-results-html/$book-name

The file results.txt should contain two parts:

1. results.html generated by Emender
2. results.json generated by Emender as well

The service will separate those two parts automatically, so please don't try to fool it :)

Return value:

{"status":"ok"}

Run test against given repository and branch

Address: http://$hostname:$port/api/v1/run-test/$book-name

Method: POST

Example:

$ curl -X POST --header "Content-Type: application/json" -d "@testinfo.json" -v "localhost:3000/api/v1/run-test/doc-Test-Book1+(test)"

Content of testinfo.json

{
    "repository": {
        "url" : "git@github.com:emender/emender-testbook.git"
        "branch" : "master"
    },
    "tests": [
        "Test1",
        "Test2",
    ]
}

Possible return values:

{"status":"ok","results":{"Test1": actual test results}}
{"status":"repo-clone-failed"}

License

Copyright © 2016 Pavel Tisnovsky ptisnovs@redhat.com, Red Hat

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.