Testflinger is a microservice that provides an API to request tests and place the tests on a queue which can be serviced by any agent capable of handling the test.
Before installing testflinger, you will need to have a redis server available somewhere. By default, testflinger will try to attach to one on localhost, but if you prefer, you can configure it to use a redis server on another server.
To create a virtual environment and install testflinger:
$ virtualenv -p python3 env
$ . env/bin/activate
$ ./setup installTo run all the tests, install tox from packages or pypi and just run:
$ toxAlso, you can run just the unit tests directly by installing and running pytest
After installing testflinger, you can run a test server locally with:
$ gunicorn testflinger:appThis will only allow connections from localhost by default. If you wish to allow external connections, use the ''--bind'' option:
$ gunicorn --bind 0.0.0.0 testflinger:appConfiguration values can be loaded from a file. By default, testflinger will look for testflinger.conf in the testflinger source directory. If you want to change the location for the configuration file, set the environment variable TESTFLINGER_CONFIG to the path of your configuration file. If no config file is found, defaults will be used.
Currently supported configuration values are:
- DATA_PATH: directory where result files will be stored
- Default: ''/data'' under the testflinger module directory
- REDIS_HOST: host or ip of the redis server
- Default: ''localhost''
- REDIS_PORT: port of the redis server
- Default: ''6379''
[POST] /v1/job - Create a test job request and place it on the specified queue
Most parameters passed in the data section of this API will be specific to the type of agent receiving them. The job_queue parameter is used to designate the queue used, but all others will be passed along to the agent.
Parameters:
- job_queue (JSON): queue name to use for processing the job
Returns:
{"job_id": <job_id> } (as JSON)
Status Codes:
- HTTP 200 (OK)
Example:
$ curl http://localhost:8000/v1/job -X POST \ --header "Content-Type: application/json" \ --data '{ "job_queue": "myqueue", "option":"foo" }'
[GET] /v1/job - Get a test job from the specified queue(s)
When an agent wants to request a job for processing, it can make this request along with a list of one or more queues that it is configured to process. The server will only return one job.
Parameters:
- queue (multivalue): queue name(s) that the agent can process
Returns:
JSON job data that was submitted by the requestor, or nothing if no jobs in the specified queue(s) are available.
Status Codes:
- HTTP 200 (OK)
- HTTP 400 (Bad Request) - this is returned if no queue is specified
- HTTP 204 (NO DATA) - if there are no jobs in the specified queues
Example:
$ curl http://localhost:8000/v1/job?queue=foo\&queue=bar
[POST] /v1/result/<job_id> - post job outcome data for the specified job_id
Parameters:
- job_id: test job identifier as a UUID
Status Codes:
- HTTP 200 (OK)
Example:
$ curl http://localhost:8000/v1/result/00000000-0000-0000-0000-000000000000 \ -X POST --header "Content-Type: application/json" \ --data '{ "exit_code": 0, "output":"foo" }'
[GET] /v1/result/<job_id> - return previously submitted job outcome data
Parameters:
- job_id: test job identifier as a UUID
Status Codes:
- HTTP 200 (OK)
- HTTP 204 (NO DATA) if there are no results for that ID yet
Returns:
JSON data previously submitted to this job_id via the POST API
Example:
$ curl http://localhost:8000/v1/result/00000000-0000-0000-0000-000000000000 \ -X GET
[POST] /v1/result/<job_id>/artifact - upload a file artifact for the specified job_id
Parameters:
- job_id: test job identifier as a UUID
Status Codes:
- HTTP 200 (OK)
Example:
$ curl -X POST -F \ "file=@README.rst" localhost:8000/v1/result/00000000-0000-0000-0000-000000000000/artifact
[GET] /v1/result/<job_id>/artifact - download previously submitted artifact for this job
Parameters:
- job_id: test job identifier as a UUID
Status Codes:
- HTTP 200 (OK)
- HTTP 204 (NO DATA) if there are no results for that ID yet
Returns:
JSON data previously submitted to this job_id via the POST API
Example:
$ curl http://localhost:8000/v1/result/00000000-0000-0000-0000-000000000000/artifact \ -X GET -O artifact.tar.gz
[POST] /v1/agents/queues - post names/descriptions of queues serviced by this agent
Status Codes:
- HTTP 200 (OK)
Example:
$ curl http://localhost:8000/v1/agents/queues \ -X POST --header "Content-Type: application/json" \ --data '{ "myqueue": "queue 1", "myqueue2": "queue 2" }'
[GET] /v1/agents/queues - retrieve the list of well-known queues
Status Codes:
- HTTP 200 (OK)
Returns:
JSON data previously submitted by all agents via the POST API
Example:
$ curl http://localhost:8000/v1/agents/queues \ -X GET
[POST] /v1/agents/images - post known images for the specified queue
Status Codes:
- HTTP 200 (OK)
Example:
$ curl http://localhost:8000/v1/agents/images \ -X POST --header "Content-Type: application/json" \ --data '{ "myqueue": { "image1": "url: http://place/imgae1" }}'
[GET] /v1/agents/images/<queue> - retrieve all known image names and the provisioning data used for them, for the specified queue
Parameters:
- queue: name of the queue to use
Status Codes:
- HTTP 200 (OK)
Returns:
JSON data previously submitted by all agents via the POST API
Example:
$ curl http://localhost:8000/v1/agents/images/myqueue \ -X GET
[POST] /v1/job/<job_id>/action - execute action for the specified job_id
Parameters:
- job_id: test job identifier as a UUID
Status Codes:
- HTTP 200 (OK)
- HTTP 400 (Bad Request) - the job is already completed or cancelled
- HTTP 404 (Not Found) - the job isn't found
Supported Actions:
- Cancel - cancel a job that hasn't been completed yet
Example:
$ curl http://localhost:8000/v1/job/00000000-0000-0000-0000-000000000000/action \ -X POST --header "Content-Type: application/json" \ --data '{ "action":"cancel" }'