gabbi promises relief by providing a language-agnostic, nicely readable and lightweight format for testing - and thus describing - HTTP APIs. Originally created as part of an effort to improve OpenStack’s APIs, it has since grown into a useful tool for anyone working with HTTP.

gabbi tests are simply YAML files that describe HTTP requests and responses. We’ll be using the wonderful httpbin for illustration purposes:

tests:

- name: supports unencrypted connections
  method: GET
  url: http://httpbin.org/
  status: 200

- name: supports SSL encryption
  method: GET
  url: https://httpbin.org/
  status: 200

method and status are optional, but it’s nice to be explicit. In fact, gabbi itself states that the name is „derived from ‚gabby‘: excessively talkative“ - i.e. gabbi prefers direct visibility and readability.

Of course we need to install gabbi in order to run these tests:

$ pip install gabbi

Using a virtual environment can help avoid sudo privileges or polluting our global packages directory.

Once that’s done, we can feed our YAML tests to gabbi:

$ gabbi-run < http.yaml
... E supports unencrypted connections
... E supports SSL encryption

ERROR: supports unencrypted connections
	[Errno 61] Connection refused
ERROR: supports SSL encryption
	[Errno 61] Connection refused
----------------------------------------------------------------------
Ran 2 tests in 0.015s

FAILED (errors=2)

Oops - I wasn’t connected to the internet. Of course we’d typically test a local development server instead, but that’s not important right now. Let’s try this again:

$ gabbi-run < http.yaml
... ✓ supports unencrypted connections
... ✓ supports SSL encryption

----------------------------------------------------------------------
Ran 2 tests in 0.681s

We don’t want to hard-code the target host, so let’s use paths instead of fully qualified URLs:

tests:

  - name: reports available HTTP methods
    method: OPTIONS
    url: /

    response_headers:
        allow: HEAD, OPTIONS, GET

  - name: front page returns HTML
    method: GET
    url: /

    status: 200
    response_headers:
        content-type: text/html; charset=utf-8

(Note that I added some vertical whitespace to separate request and response - that’s still valid YAML, of course.)

$ gabbi-run httpbin.org < http.yaml
... ✓ reports available HTTP methods
... ✓ front page returns HTML

----------------------------------------------------------------------
Ran 2 tests in 0.457s

That all seems pretty straightforward so far. Let’s ensure that the Allow header did in fact tell us the truth:

tests:

  - name: submitting data is not allowed
    method: POST
    url: /
    request_headers:
        content-type: text/plain
    data: lorem ipsum

    status: 405
$ gabbi-run httpbin.org < http.yaml
... ✓ submitting data is not allowed

As predicted, httpbin responded with 405 Method Not Allowed - clearly we’ll need to send our precious data to a different route:

tests:

  - name: form submission
    method: POST
    url: /post
    request_headers:
        content-type: application/x-www-form-urlencoded
    data: title=hello%20world&comment=lorem%20ipsum%21

    status: 200
$ gabbi-run httpbin.org < http.yaml
... ✓ form submission

Ah, there we go. Note that it’s our responsibility to encode the data there - that’s a little easier if we use JSON:

tests:

  - name: submitting JSON
    method: POST
    url: /post
    request_headers:
        content-type: application/json
    data:
        title: hello world
        comment: lorem ipsum dolor sit amet
$ gabbi-run httpbin.org < http.yaml
... ✓ submitting JSON

In fact, httpbin responds with JSON, returning in the response whatever data we submit in our request. We can use JSONPath to query that response data:

tests:

  - name: parsing JSON
    method: POST
    url: /post
    request_headers:
        accept: application/json
        content-type: application/json
    data:
        title: hello world
        comments: lorem ipsum dolor sit amet

    status: 200
    response_headers:
        content-type: application/json
    response_json_paths:
        $.json.title: hello world
        $.json.comments: lorem ipsum dolor sit amet
$ gabbi-run httpbin.org < http.yaml
... ✓ parsing JSON

It’s also possible to use data from the preceding response in a new request:

tests:

  - name: "consecutive redirects - step #1"
    method: GET
    url: /relative-redirect/2

    status: 302
    response_headers:
        location: /relative-redirect/1

  - name: "consecutive redirects - step #2"
    method: GET
    url: $LOCATION

    status: 302
    response_headers:
        location: /get
$ gabbi-run httpbin.org < http.yaml
... ✓ consecutive redirects - step #1
... ✓ consecutive redirects - step #2

Here we’re just using the Location header, but this technique also enables us to go full HATEOAS and test hypermedia APIs:

tests:

  - name: set up a hypermedia response
    method: PUT
    url: /put
    request_headers:
        accept: application/json
        content-type: application/json
    data:
        title: hello world
        links:
            next: http://httpbin.org/cookies/set?foo=bar

  - name: follow "next" link from preceding response
    method: GET
    url: $RESPONSE['$.json.links.next']

    status: 302
    response_headers:
        set-cookie: foo=bar; Path=/
$ gabbi-run httpbin.org < http.yaml
... ✓ set up a hypermedia response
... ✓ follow "next" link from preceding response

Obviously coercing httpbin into providing hypermedia responses is a bit of a hack, so we’ll stop here. Hopefully this is sufficient to get started - in a future post, we might expand on this with a more realistic example. We might also delve into gabbi’s extensibility, e.g. creating a custom response handler to query HTML responses with CSS selectors.

Feel free to join the IRC channel #gabbi on FreeNode or leave feedback via Twitter.

TAGS