APICheck
A tool and framework for testing JSON based web APIs. Written in Python.
The tool and framework can be used to run a set of tests defined in a simple JSON configuration file. Each test can check the HTTP response from a request to a particular endpoint against expected JSON values or types.
Installation
The easiest way to install is by using pip:
sudo pip install apicheck
Otherwise from the command line:
git clone https://github.com/kuykendb/APICheck
cd apicheck
sudo python setup.py install
NOTE: the current beta release has only been tested with Python v3. Testing will soon be done for v2 as well.
Usage
The tool must be provided a JSON file of tests to be run. A basic example of a file of tests is:
[
{
"name":"My First Test",
"url":"/posts/1",
"method":"GET",
"expected_response_values":{
"id":1
},
"expected_response_types":{
"body":"string"
}
}
]
You can run the above example test by saving the above JSON in a file called "tests.json" and then by running the following command:
apicheck http://jsonplaceholder.typicode.com tests.json
This runs a test against an API that provides fake JSON responses for testing purposes. You should see the following after running this test:
{
"test_results": [
{
"status": "PASSED",
"elapsed_time": 1.021967887878418,
"name": "My First Test"
}
],
"summary": {
"total_elapsed_time": 1.0219738483428955,
"passed": 1,
"success_percentage": 100.0,
"failed": 0
}
}
If you don't need the output in JSON and want to see a more human readable
output, then just pass the flag -f
or --format
with the argument text
:
For example:
apicheck http://jsonplaceholder.typicode.com tests.json -f text
Test File Format
The JSON file of tests must contain an array of test objects. Each test object must contain the following required keys:
name: a string describing the test
endpoint: the endpoint to be tested which will be appended to the base url
method: the HTTP request method - either GET or POST
Each test can run any number of checks on the JSON response object returned by the request. Each check can test that a key in the response is mapped to the correct value or the correct type.
Checking Response Values
Checks for expected values are described in the expected_response_values
map
for each test.
For example if we expect the JSON response to have an id
key with a value of 2
and a title
key with a value of qui est esse
then our expected_response_values
map would look like the following:
"expected_response_values":{
"id":2,
"title": "qui est esse"
}
Checking Response Types
Checks for expected tyles are described in the expected_response_types
map for
each test.
For example if we expect the JSON response to have an id
key with an int
value
and a title
key with a string
value, then our expected_response_types
"expected_response_types":{
"id":"int",
"title": "string"
}
The expected types that can be checked are:
string
int
float
Full Example Test File
The following is a full example of a simple test file:
[
{
"name":"My First Test",
"url":"/posts/1",
"method":"GET",
"expected_response_values":{
"id":1
}
},
{
"name":"My Second Test",
"url":"/posts/2",
"method":"GET",
"expected_response_values":{
"id":2,
"title":"qui est esse"
},
"expected_response_types":{
"userId":"int",
"body":"string"
}
},
{
"name":"My Third Test",
"url":"/posts/3",
"method":"GET",
"expected_response_types":{
"userId":"int",
"title":"string",
"body":"string"
}
}
]
To run the above example, save the JSON in a file called tests.json
and then
run the following command:
apicheck http://jsonplaceholder.typicode.com tests.json
API Documentation / Guide
APICheck also provides an interface through which testing can be performed from within other Python modules. This part of the documentation covers all the provided classes and methods.
Documentation coming soon...
Future Features
- More advanced checks - e.g. for arrays, nested maps, etc
- More friendly interface for use as module within other Python applications.
- Support for authentication headers, non-json request bodys