Using BDD with web-services: a tutorial using JBehave and Thucydides

the story files contain the bdd-style  given-when-then  scenarios that describe how the web service should behave. when you design a web service using bdd, you can express behavior at two levels (and many projects use both). the first approach is to describe the json data in the bdd scenarios, as illustrated here:

scenario: shorten urls
given a url http://www.google.com
when i request the shortened form of this url
then i should obtain the following json message:
 {
  "kind": "urlshortener#url",
  "id": "http://goo.gl/fbss",
  "longurl": "http://www.google.com/"
 }

this works well if your scenarios have a very technical audience (i.e. if you are writing a web service purely for other developers), and if the json contents remain simple. it is also a good way to agree on the json format that the web sevice will produce. but if you need to discuss the scenario with business, bas or even testers, and/or if the json that you are returning is more complicated, putting json in the scenarios is not such a good idea. this approach also works poorly for soap-based web services where the xml message structure is more complex. a better approach in these situations is to describe the inputs and expected outcomes in business terms, and then to translate these into the appropriate json format within the step definition:

scenario: shorten urls
given a url <providedurl>
when i request the shortened form of this url
then the shortened form should be <expectedurl>
examples:
| providedurl             | expectedurl        |
| http://www.google.com/  | http://goo.gl/fbss |
| http://www.amazon.com/  | http://goo.gl/xj57 |

let's see how we would automate this scenario using jbehave and thucydides. first, we need to write jbehave step definitions in java for each of the  given/when/then  steps in the scenarios we just saw. create a class called  processingurls  next to the  acceptancetestsuite  class, or in a subdirectory underneath this class.

public class processingurls {
    string providedurl;
    string returnedmessage;
    @steps
    urlshortenersteps urlshortener;
    @given("a url <providedurl>")
    public void givenaurl(string providedurl) {
        this.providedurl = providedurl;
    }
    @when("i request the shortened form of this url")
    public void shortenurl() {
        returnedmessage = urlshortener.shorten(providedurl);
    }
    @when("i request the expanded form of this url")
    public void expandurl() {
        returnedmessage = urlshortener.expand(providedurl);
    }
    @then("the shortened form should be <expectedurl>")
    public void shortenedformshouldbe(string expectedurl) throws jsonexception {
        urlshortener.response_should_contain_shortened_url(returnedmessage, expectedurl);
    }
}

now add the  urlshortenersteps  class. this class contains the actual test code that interacts with your web service we could use any java rest client for this, but here we are using the  spring resttemplate  . the full class looks like this:

public class urlshortenersteps extends scenariosteps {
    resttemplate resttemplate;
    public urlshortenersteps() {
        resttemplate = new resttemplate();
    }
    @step("longurl={0}")
    public string shorten(string providedurl) {
        map<string, string> urlform = new hashmap<string, string>();
        urlform.put("longurl", providedurl);
        return resttemplate.postforobject("https://www.googleapis.com/urlshortener/v1/url", urlform, string.class);
    }
    @step("shorturl={0}")
    public string expand(string providedurl) {
        return resttemplate.getforobject("https://www.googleapis.com/urlshortener/v1/url?shorturl={shorturl}", string.class, providedurl);
    }
    @step
    public void response_should_contain_shortened_url(string returnedmessage, string expectedurl) throws jsonexception {
        string expectedjsonmessage = "{'id':'" + expectedurl + "'}";
        jsonassert.assertequals(expectedjsonmessage, returnedmessage, jsoncomparemode.lenient);
    }
    @step
    public void response_should_contain_long_url(string returnedmessage, string expectedurl) throws jsonexception {
        string expectedjsonmessage = "{'longurl':'" + expectedurl + "'}";
        jsonassert.assertequals(expectedjsonmessage, returnedmessage, jsoncomparemode.lenient);
    }
}

the spring resttemplate class is an easy way to interact with a web service with a minimum of fuss. in the  shorten()  method, we invoke the  urlshortener  web service using a post operation to shorten a url:

   @step("longurl={0}")
    public string shorten(string providedurl) {
        map<string, string> urlform = new hashmap<string, string>();
        urlform.put("longurl", providedurl);
        return resttemplate.postforobject("https://www.googleapis.com/urlshortener/v1/url", urlform, string.class);
    }

the expand service is even simpler to call, as it just uses a simple get operation:

    @step("shorturl={0}")
    public string expand(string providedurl) {
        return resttemplate.getforobject("https://www.googleapis.com/urlshortener/v1/url?shorturl={shorturl}", string.class, providedurl);
    }

in both cases, we return the json document produced by the web service, and verify the contents in the  then  step using the  jsonassert  library. there are many libraries you can use to verify the json data returned from a web service. if you need to check the entire json structure, jsonassert provides a convenient api to do so. jsonassert lets you match json documents strictly (all the elements must match, in the right order), or leniently (you only specify a subset of the fields that need to appear in the json document, regardless of order).

the following step checks that the json documet contains an id field with the expected url value. the full json document will appear in the reports because it is being passed as a parameter to this step.

    @step
    public void response_should_contain_shortened_url(string returnedmessage, string expectedurl) throws jsonexception {
        string expectedjsonmessage = "{'id':'" + expectedurl + "'}";
        jsonassert.assertequals(expectedjsonmessage, returnedmessage, jsoncomparemode.lenient);
    }

you can run these scenarios using  mvn verify  from the command line: this will produce the test reports and the thucydides living documentation for these scenarios. once you have run  mvn verify  , open the  index.html  file in the  target/site/thucydides  directory. this gives an overview of the test results. if you click on the  requirements  tab, you will see an overview of the results in terms of capabilities and features. we call this "feature coverage":

drill down into the "shorten urls" test result. here you will see a summary of the story or feature illustrated by this scenario:

 and if you scroll down further, you will see the details of how this web service was tested, including the json document returned by the service: 

bdd is a great fit for developing and testing web services. if you want to learn more about bdd, be sure to check out the  bdd  ,  tdd  and  test automation  workshops we are running in sydney and melbourne this may!

    john ferguson smart is a well-regarded consultant, coach, and trainer in technical agile practices based in sydney, australia. a prominent international figure in the domain of behaviour driven development, automated testing and software life cycle development optimisation, john helps organisations around the world to improve their agile development practices and to optimise their java development processes and infrastructures. he is the author of several books, most recently   bdd in action   for manning.