Skip to main content

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

Posted by johnsmart on April 22, 2014 at 1:42 AM PDT

Behavior Driven Development (BDD) is an approach that uses conversions around concrete examples to discover, describe and formalize the behavior of a system. BDD tools such as JBehave and Cucumber are often used for writing web-based automated acceptance testing. But BDD is also an excellent approach to adopt if you need to design a web service. In this article, we will see how you can use JBehave and Thucydides to express and to automate clear, meaningful acceptance criteria for a RESTful web service. (The general approach would also work for a web service using SOAP.) We will also see how the reports (or "living documentation", in BDD terms) generated by these automated acceptance criteria also do a great job to document the web service.

Thucydides is an open source BDD reporting and acceptance testing library that is used in conjunction with other testing tools, either BDD testing frameworks such as JBehave, SpecFlow, or more traditional libraries such as JUnit.

Web services are easy to model and test using BDD techniques, in many ways more so than web applications. Web services are (or should be) relatively easy to describe in behavioral terms. They accept a well-defined set of input parameters, and return a well-defined result. So they fit well into the typical BDD-style way of describing behavior, using given-when-then format:

Given some precondition
When something happens
Then a particular outcome is expected

During the rest of this article we will see how to describe and automate web service behavior in this way. To follow along, you will need Java and Maven installed on your machine (I used Java 8 and Maven 3.2.1). The source code is also available on Github. If you want to build the project from scratch, first create a new Thucydides/JBehave project from the command line like this:
mvn archetype:generate -Dfilter=thucydides-jbehave
Enter whatever artifact and group names you like: it doesn't make any difference for this example:

Choose archetype:
1: local -> net.thucydides:thucydides-jbehave-archetype (Thucydides automated acceptance testing project using Selenium 2, JUnit and JBehave)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
Define value for property 'groupId': : com.wakaleo.training.webservices
Define value for property 'artifactId': : bdddemo
Define value for property 'version':  1.0-SNAPSHOT: : 1.0.0-SNAPSHOT
Define value for property 'package':  com.wakaleo.training.webservices: :
Confirm properties configuration:
groupId: com.wakaleo.training.webservices
artifactId: bdddemo
version: 1.0.0-SNAPSHOT
package: com.wakaleo.training.webservices
Y: :

This will create a simple project set up with JBehave and Thucydides. It is designed to test web applications, but it is easy enough to adapt to work with a RESTful web service. We don't need the demo code, so you can safely delete all of the Java classes (except for the AcceptanceTestSuite class) and the JBehave .story files.

Now, update the pom.xml file to use the latest version of Thucydides, e.g.

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <thucydides.version>0.9.239</thucydides.version>
    <thucydides.jbehave.version>0.9.235</thucydides.jbehave.version>
</properties>

Once you have done this, you need to define some stories and scenarios for your web service. To keep things simple in this example, we will be working with two simple requirements: shortening and expanding URLs using Google's URL shortening service. We will describe these in two JBehave story files. Create a stories directory under src/test/resources, and create a sub-directory for each requirement called expanding_urls and shortening_urls. Each directory represents a high-level capability that we want to implement. Inside these directories we place JBehave story files (expanding_urls.story and shortening_urls.story) for the features we need. (This structure is a little overkill in this case, but is useful for real-world project where the requirements are more numerous and more complex). This structure is shown here:

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.

The step definitions for this scenario are simple, and largely delegate to a class called UrlShortenerSteps to do the heavy-weight work. This approach make a cleaner separation of th what from the how, and makes reuse easier - for example, if we need to change underlying web service we used to implement the URL shortening feature, these step definitions should remain unchanged:

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.

Comments

I have no idea about click_link with in jbehave frame work ...

I have no idea about click_link with in jbehave frame work and I want to learn more about BDD, please let me know any Solution Provider for that?

step files are not recongnized , do we have any ...

step files are not recongnized , do we have any configuration required when i run the main junit test case .

And all my test cases goes to pending

Take a look at the sample code on Github: ...

Take a look at the sample code on Github: https://github.com/thucydides-webtests/webservice-demo

Hi, Do You have a sample code for a web based ...

Hi,

Do You have a sample code for a web based application

Jbehave , Thucydides and selenium

I am using the Thucydides-Jbehave Show case from git hub , which ends in to all pending tests.

Do we have a sample project for executing web based automation with thucydides jbehave

When i am running my tests everything says pending ,

as you mentioned in thucydides reference manual .

There is no configuration required for junit to identify the tests if there are in the same package , but its not identifying .

help me out in understandting how testsuite could be able to identify the step files .

This above is mentioned about Jbehave and Thucydides project