• A REST testing and API microbenchmarking tool
• Tests are defined in basic YAML or JSON config files, no code needed
• Minimal dependencies (pycurl, pyyaml), making it easy to deploy on-server for smoketests/healthchecks
• Supports generate/extract/validate mechanisms to create full test scenarios
• Returns exit codes on failure, to slot into automated configuration management/orchestration tools (also supplies parseable logs)
• Logic is written and extensible in Python

Apache License, Version 2.0

and Changelog

This will check that APIs accept operations, and will smoketest an application

---
- config:
    - testset: "Basic tests"

- test: 
    - name: "Basic get"
    - url: "/api/person/"
- test: 
    - name: "Get single person"
    - url: "/api/person/1/"
- test: 
    - name: "Delete a single person, verify that works"
    - url: "/api/person/1/"
    - method: 'DELETE'
- test: # create entity by PUT
    - name: "Create/update person"
    - url: "/api/person/1/"
    - method: "PUT"
    - body: '{"first_name": "Gaius","id": 1,"last_name": "Baltar","login": "gbaltar"}'
    - headers: {'Content-Type': 'application/json'}
    - validators:  # This is how we do more complex testing!
        - compare: {header: content-type, comparator: contains, expected:'json'}
        - compare: {jsonpath_mini: 'login', expected: 'gbaltar'}  # JSON extraction
        - compare: {raw_body:"", comparator:contains, expected: 'Baltar' }  # Tests on raw response
- test: # create entity by POST
    - name: "Create person"
    - url: "/api/person/"
    - method: "POST"
    - body: '{"first_name": "William","last_name": "Adama","login": "theadmiral"}'
    - headers: {Content-Type: application/json}

• Here's a really good example for how to create a user and then do tests on it.
  • This shows how to use extraction from responses, templating, and different test types
• If you're trying to do something fancy, take a look at the content-test.yaml.
  • This shows most kinds of templating & variable uses. It shows how to read from file, using a variable in the file path, and templating on its content!
• There's a whole folder of example tests to help get started

The best way to install PyRestTest is via Python's pip packaging tool.

If that is not installed, we'll need to install it first:

• Ubuntu/Debian: (sudo) apt-get install python-pip
• CentOS/RHEL: (sudo) yum install python-pip
• Mac OS X with homebrew: brew install python (it's included)
• Or with just python installed: wget https://bootstrap.pypa.io/get-pip.py && sudo python get-pip.py

Then install package python-pycurl:

• Ubuntu: (sudo) apt-get install python-pycurl
• CentOS/RHEL: (sudo) yum install python-pycurl This is needed because the pycurl dependency may fail to install by pip.

Then we install pyresttest:

sudo pip install pyresttest

If it fails like this: __main__.ConfigurationError: Could not run curl-config: [Errno 2] No such file or directory

Then you need to install python-pycurl (pip tried and failed to install it)

There are also options to install from repo, or build an RPM.

• The Quickstart is below.
• Benchmarking has its own section below
• Advanced features have separate documentation (templating, generators, content extraction, complex validation).
• How to extend PyRestTest is its own document

The root folder of this library also includes a ton of example tests.

Run a basic test of the github API:

resttest.py https://api.github.com examples/github_api_smoketest.yaml

A simple set of tests that show how json validation can be used to check contents of a response. Test includes both successful and unsuccessful validation using github API.

resttest.py https://api.github.com examples/github_api_test.yaml

(For help: python resttest.py --help )

Same as the other test but running in interactive mode.

resttest.py https://api.github.com examples/github_api_test.yaml --interactive true --print-bodies true

resttest.py https://api.github.com examples/github_api_test.yaml --log debug

Now, let's get started!

Most quickstarts show a case where everything works perfectly.

That is not what we're going to do today.

We're going to break things horribly and enjoy it!

This is what testing is for.

• Linux or Mac OS X with python 2.6+ or 2.7 installed and pycurl
• Do not use a virtualenv (or have it custom configured to find libcurl)

In order to get started with PyRestTest, we will need a REST service with an API to work with.

Fortunately, there is a small RESTful service included with the project.

Let's grab a copy of the code to start:

git clone https://github.com/svanoort/pyresttest.git

Then we'll install the necessary dependencies to run it (Django and Django Tastypie):

sudo pip install 'django >=1.6, <1.7' django-tastypie

Now we start a test server in one terminal (on default port 8000) with some preloaded data, and we will test in a second terminal:

cd pyresttest/pyresttest/testapp
python manage.py testserver test_data.json

If you get an error like this, it's because you're using Python 2.6, and are trying to run a Django version not compatible with that:

Traceback (most recent call last):
  File "/usr/bin/django-admin.py", line 2, in <module>
    from django.core import management
  File "/usr/lib64/python2.6/site-packages/django/core/management/__init__.py", line 68
    commands = {name: 'django.core' for name in find_commands(__path__[0])}

This is easy enough to fix though by installing a compatible Django version:

sudo pip uninstall -y django django-tastypie
sudo pip install 'django >=1.6, <1.7' django-tastypie

Before going deeper, let's make sure that server works okay... in our second terminal, we run this:

curl -s http://localhost:8000/api/person/2/ | python -m json.tool

If all is good, we ought to see a result like this:

{
    "first_name": "Leeroy", 
    "id": 2, 
    "last_name": "Jenkins", 
    "login": "jenkins", 
    "resource_uri": "/api/person/2/"
}

Now, we've got a small but working REST API for PyRestTest to test on!

In our second terminal, we're going to create a basic REST smoketest, which can be used to test the server came up cleanly and works.

Pop up ye olde text editor of choice and save this to a file named 'test.yaml':

---
- config:
    - testset: "Quickstart app tests"

- test:
    - name: "Basic smoketest"
    - url: "/api/people/"

And when we run it:

resttest.py http://localhost:8000 test.yaml

OOPS! As the more observant people will notice, we got the API URL wrong, and the test failed, showing the unexpected 404, and reporting the test name. At the end we see the summary, by test group ("Default" is exactly like what it sounds like).

Let's fix that, add a test group name, and re-run it!

---
- config:
    - testset: "Quickstart app tests"

- test:
    - group: "Quickstart"
    - name: "Basic smoketest"
    - url: "/api/person/"

Ahh, much better! But, that's very basic, surely we can do better?

Let's build this out into a full test scenario, creating and deleting a user:

We're going to add a create for a new user, that scoundrel Gaius Baltar:

---
- config:
    - testset: "Quickstart app tests"

- test:
    - group: "Quickstart"
    - name: "Basic smoketest"
    - url: "/api/person/"

- test:
    - group: "Quickstart"
    - name: "Create a person"
    - url: "/api/person/10/"
    - method: "PUT"
    - body: '{"first_name": "Gaius","id": 10,"last_name": "Baltar","login": "baltarg"}'

... and when we run it, it fails (500 error). That sneaky lowdown tried to sneak in without a Content-Type so the server knows what he is.

Let's fix it...

- test:
    - group: "Quickstart"
    - name: "Create a person"
    - url: "/api/person/10/"
    - method: "PUT"
    - body: '{"first_name": "Gaius","id": 10,"last_name": "Baltar","login": "baltarg"}'
    - headers: {'Content-Type': 'application/json'}

... and now both tests will pass. Then let's add a test the person is really there after:

---
- config:
    - testset: "Quickstart app tests"

- test:
    - group: "Quickstart"
    - name: "Basic smoketest"
    - url: "/api/person/"

- test:
    - group: "Quickstart"
    - name: "Create a person"
    - url: "/api/person/10/"
    - method: "PUT"
    - body: '{"first_name": "Gaius","id": 10,"last_name": "Baltar","login": "baltarg"}'
    - headers: {'Content-Type': 'application/json'}

- test:
    - group: "Quickstart"
    - name: "Make sure Mr Baltar was added"
    - url: "/api/person/10/"

Except there is a problem with this... the third test will pass if Baltar already existed in the database. Let's test he wasn't there beforehand...

---
- config:
    - testset: "Quickstart app tests"

- test:
    - group: "Quickstart"
    - name: "Make sure Mr Baltar ISN'T there to begin with"
    - url: "/api/person/10/"
    - expected_status: [404]

- test:
    - group: "Quickstart"
    - name: "Basic smoketest"
    - url: "/api/person/"

- test:
    - group: "Quickstart"
    - name: "Create a person"
    - url: "/api/person/10/"
    - method: "PUT"
    - body: '{"first_name": "Gaius","id": 10,"last_name": "Baltar","login": "baltarg"}'
    - headers: {'Content-Type': 'application/json'}

- test:
    - group: "Quickstart"
    - name: "Make sure Mr Baltar is there after we added him"
    - url: "/api/person/10/"

Much better, now the first test fails... so, let's add a delete for that user at the end of the test, and check he's really gone.

---
- config:
    - testset: "Quickstart app tests"

- test:
    - group: "Quickstart"
    - name: "Make sure Mr Baltar ISN'T there to begin with"
    - url: "/api/person/10/"
    - expected_status: [404]

- test:
    - group: "Quickstart"
    - name: "Basic smoketest"
    - url: "/api/person/"

- test:
    - group: "Quickstart"
    - name: "Create a person"
    - url: "/api/person/10/"
    - method: "PUT"
    - body: '{"first_name": "Gaius","id": 10,"last_name": "Baltar","login": "baltarg"}'
    - headers: {'Content-Type': 'application/json'}

- test:
    - group: "Quickstart"
    - name: "Make sure Mr Baltar is there after we added him"
    - url: "/api/person/10/"

- test:
    - group: "Quickstart"
    - name: "Get rid of Gaius Baltar!"
    - url: "/api/person/10/"
    - method: 'DELETE'

- test:
    - group: "Quickstart"
    - name: "Make sure Mr Baltar ISN'T there after we deleted him"
    - url: "/api/person/10/"
    - expected_status: [404]

And now we have a full lifecycle test of creating, fetching, and deleting a user via the API.

Basic authentication is supported:

---
- config:
    - testset: "Quickstart authentication test"

- test:
    - name: "Authentication using basic auth"
    - url: "/api/person/"
    - auth_username: "foobar"
    - auth_password: "secret"
    - expected_status: [200]

This is just a starting point, see the advanced guide for the advanced features (templating, generators, content extraction, complex validation).

• Simple templating of HTTP request bodies, URLs, and validators, with user variables
• Generators to create dummy data for testing, with support for easily writing your own
• Sequential tests: extract info from one test to use in the next
• Import test sets in other test sets, to compose suites of tests easily
• Easy benchmarking: convert any test to a benchmark, by changing the element type and setting output options if needed
• Lightweight benchmarking: ~0.3 ms of overhead per request, and plans to reduce that in the future
• Accurate benchmarking: network measurements come from native code in LibCurl, so test overhead doesn't alter them
• Optional interactive mode for debugging and demos

As you can see, tests are defined in YAML format.

There are 5 top level test syntax elements:

• url: a simple test, fetches given url via GET request and checks for good response code
• test: a fully defined test (see below)
• benchmark: a fully defined benchmark (see below)
• config or configuration: overall test configuration
• import: import another test set file so you Don't Repeat Yourself

---
# Will load the test sets from miniapp-test.yaml and run them
- import: examples/miniapp-test.yaml

A simple URL test is equivalent to a basic GET test with that URL

---
- config:
    - testset: "Basic tests"
- url: "/api/person/"  # This is a simple test
- test: 
    - url: "/api/person/"  # This does the same thing

For advanced cases, sometimes you will want to use custom Curl settings that don't have a corresponding option in PyRestTest.

This is easy to do: for each test, you can specify custom Curl arguments with 'curl_option_optionname.' For this, 'optionname' is case-insensitive and the optionname is a Curl Easy Option with 'CURLOPT_' removed.

For example, to follow redirects up to 5 times (CURLOPT_FOLLOWLOCATION and CURLOPT_MAXREDIRS):

---
- test: 
    - url: "/api/person/1"
    - curl_option_followlocation: True
    - curl_option_maxredirs: 5  

Note that while option names are validated, no validation is done on their values.

Whenever possible, I've tried to make reading configuration Be Smart And Do The Right Thing. That means type conversions are handled wherever possible, and fail early if configuration is nonsensical.

We're all responsible adults: don't try to give a boolean or list where an integer is expected and it'll play nice.

One caveat: if you define the same element (example, URL) twice in the same enclosing element, the last value will be used. In order to preserve sanity, I use last-value wins.

Oh, yes please! PyRestTest allows you to collect low-level network performance metrics from Curl itself.

Benchmarks are based off of tests: they extend the configuration elements in a test, allowing you to configure the REST call similarly. However, they do not perform validation on the HTTP response, instead they collect metrics.

There are a few custom configuration options specific to benchmarks:

• warmup_runs: (default 10 if unspecified) run the benchmark calls this many times before starting to collect data, to allow for JVM warmup, caching, etc
• benchmark_runs: (default 100 if unspecified) run the benchmark this many times to collect data
• output_file: (default is None) file name to write benchmark output to, will get overwritten with each run, if none given, will write to terminal only
• output_format: (default CSV if unspecified) format to write the results in ('json' or 'csv'). More on this below.
• metrics: which metrics to gather (explained below), MUST be specified or benchmark will do nothing

There are two ways to collect performance metrics: raw data, and aggregated stats. Each metric may yield raw data, plus one or more aggregate values.

• Raw Data: returns an array of values, one for each benchmark run
• Aggregates: runs a reduction function to return a single value over the entire benchmark run (median, average, etc)

To return raw data, in the 'metrics' configuration element, simply input the metric name in a list of values. The example below will return raw data for total time and size of download (101 values each).

- benchmark: # create entity
    - name: "Basic get"
    - url: "/api/person/"
    - warmup_runs: 7
    - 'benchmark_runs': '101'
    - output_file: 'miniapp-benchmark.csv'
    - metrics:
        - total_time
        - size_download

Aggregates are pretty straightforward:

• mean or mean_arithmetic: arithmetic mean of data (normal 'average')
• mean_harmonic: harmonic mean of data (useful for rates)
• median: median, the value in the middle of sorted result set
• std_deviation: standard deviation of values, useful for measuring how consistent they are
• total or sum: total up the values given

Currently supported metrics are listed below, and these are a subset of Curl get_info variables. These variables are explained here (with the CURLINFO_ prefix removed): curl_easy_get_info documentation

Metrics: 'appconnect_time', 'connect_time', 'namelookup_time', 'num_connects', 'pretransfer_time', 'redirect_count', 'redirect_time', 'request_size', 'size_download', 'size_upload', 'speed_download', 'speed_upload', 'starttransfer_time', 'total_time'

CSV is the default report format. CSV ouput will include:

• Benchmark name
• Benchmark group
• Benchmark failure count (raw HTTP failures)
• Raw data arrays, as a table, with headers being the metric name, sorted alphabetically
• Aggregates: a table of results in the format of (metricname, aggregate_name, result)

In JSON, the data is structured slightly differently:

{"failures": 0,
"aggregates":
    [["metric_name", "aggregate", "aggregateValue"] ...],
"failures": failureCount,
"group": "Default",
"results": {"total_time": [value1, value2, etc], "metric2":[value1, value2, etc], ... }
}

Samples:

---
- config:
    - testset: "Benchmark tests using test app"

- benchmark: # create entity
    - name: "Basic get"
    - url: "/api/person/"
    - warmup_runs: 7
    - 'benchmark_runs': '101'
    - output_file: 'miniapp-benchmark.csv'
    - metrics:
        - total_time
        - total_time: mean
        - total_time: median
        - size_download
        - speed_download: median

- benchmark: # create entity
    - name: "Get single person"
    - url: "/api/person/1/"
    - metrics: {speed_upload: median, speed_download: median, redirect_time: mean}
    - output_format: json
    - output_file: 'miniapp-single.json'

git clone https://github.com/svanoort/pyresttest.git
cd pyresttest
sudo python setup.py install

sudo su -
easy_install pyyaml pycurl
exit

OR via pip

sudo su -
pip install pyyaml pycurl
exit

It's easy to build and install from RPM:

python setup.py bdist_rpm  # Build RPM
find -iname '*.rpm'   # Gets the RPM name

sudo yum localinstall my_rpm_name
sudo yum install PyYAML python-pycurl

• You need to install PyYAML & PyCurl manually because Python distutils can't translate python dependencies to RPM packages.

Gotcha: Python distutils add a dependency on your major python version. This means you can't build an RPM for a system with Python 2.6 on a Python 2.7 system.

You'll need to install rpm-build, and then it should work.

sudo yum install rpm-build

• The changelog is here.
• Python 2.6 and 2.7 compatible (tested on Ubuntu 14/python 2.7 and CentOS 6/python 6.6)
• Working on Python 3 support
• Releases occur every few months to PyPi once a few features are ready to go
• PyRestTest uses Semantic Versioning 2.0
• Back-compatibility is important! PyRestTest makes a strong effort to maintain command-line and YAML format back-compatibility since 1.0.
  • Extension method signatures are maintained as much as possible.
  • However, internal python implementations are subject to change.
  • Major version releases (1.x to 2.x, etc) may introduce breaking API changes, but only with a really darned good reason, and only there's not another way.

• This is written for an environment where Python is not the sole or primary langauge
• You totally can do pure-Python tests if you want!
  • Extensions provide a stable API for adding more complex functionality in python
  • All modules can be imported and used as libraries
  • Gotcha: the project is still young, so internal implementation may change often, much more than YAML features

• XML is extremely verbose and has many gotchas for parsing
• You CAN use JSON for tests, it's a subset of YAML. See miniapp-test.json for an example.
• YAML tends to be the most concise, natural, and easy to write of these three options

• No, this is a separate niche and there are already many excellent tools to fill it
• Adding load testing features would greatly increase complexity
• But some form might come eventually!

We welcome any feedback you have, including pull requests, reported issues, etc!

For instructions on building, see building.md.

For pull requests to get easily merged, please:

• Include unit tests, and verify that run_tests.sh passes
• Include documentation as appropriate
• Attempt to adhere to PEP8 style guidelines and project style

Bear in mind that this is largely a one-man, outside-of-working-hours effort at the moment, so response times will vary. That said: every feature request gets heard, and even if it takes a while, all the reasonable features will get incorporated. If you fork the main repo, check back periodically... you may discover that the next release includes something to meet your needs and then some!