Test your external API like a boss with Cucumber
Introducing an extension to Cucumber that allows BDD-style testing of API

Fork on Github

  Mar 08, 2015 -   read
  bdd, cucumber, api, testing, ruby, gem, rubygem

If it is your first time hearing about Cucumber or BDD in general, no sweat. In short, it allows you to specify your expectation in plain, readable text, meaning even your product managers can (almost) read and understand it!

However, what I like about Cucumber is less for this reason, but more for how scalable and maintainable it could be when your test suites grow over time, with features such as tagging and filtering, hooks, reusing steps, etc… I’ll let you find that out yourself, hopefully you will grow fond of writing your own BDD specs!


It is almost unimaginable now that you can find a mobile app, be it Android, iOS, Windows Phone, Blackberry, (you-name-it) that does not make HTTP requests, specifically API requests, to retrieve data for it to gracefully display on mobile/tablet. In facts, apps are so dependent on external API now that most service providers either provide us with a RESTful API, or platform-specific SDKs to consume and manipulate the data they provide.

This means that regardless of your efforts to bullet-proof your app logic with an extensive set of unit tests, there would still be a high chance it may crash in production due to changes in your external API dependency. In many cases, it would be a 3rd-party provided API that you have no control over. But either way, being automatically informed when things go wrong is still more preferrable than when you get a 1-star rating with review saying app crashed, and later find out it is due to API change!

To address the above concerns, cucumber-api extends cucumber to allow testing and verification of your API dependency in BDD style!

By now you should have been inspired by the Given-When-Then pattern, let’s try writing our API expectation in a similar fashion with cucumber-api:

Scenario: Verify top stories JSON schema
  When I send and accept JSON
  And I send a GET request to "https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty"
  Then the response status should be "200"

That’s cool! Now how about checking the item API with the first item ID retrieved from the above API?

Scenario Outline: Verify item JSON schema
  When I send and accept JSON
  And I send a GET request to "https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty"
  Then the response status should be "200"
  And the JSON response root should be array
  When I grab "$[0]" as "id"
  And I send a GET request to "https://hacker-news.firebaseio.com/v0/item/{id}.json"
  Then the response status should be "200"
  And the JSON response root should be object
  And the JSON response should have <optionality> key "<key>" of type <value type>
    | key   | value type | optionality |
    | id    | numeric    | required    |
    | score | numeric    | required    |
    | url   | string     | optional    |

And that’s just the beginning! Check the documentation to see what else you can do with cucumber-api. Once you have written a solid set of API expectation with cucumber-api, put them in as part of your daily/nightly build process and never be caught off guard by unexpected API changes again!


Be careful with requests that may alter production data. Always think twice before you put them in, or make sure that any data alteration can be safely rolled back regardless of your test results.

If you find yourself restricted with any of the functionalities, don’t be shy, go ahead and make a pull request!

Get the cucumber-api ruby gem now and be a boss!

Ha Duy Trung
Currently cooking, brewing and building Android stuffs.