- October 13, 2016

In a previous blog post, we introduced the API testing support of Restlet Client (fka DHC). We described the power of this tool to test REST services and web APIs by combining requests and assertions.

During the summer, a new version of Client was released extending this testing support by providing a new dedicated view. This view leverages concepts of the behavior-driven development (BDD) to allow different actors, not necessarily technical ones, to take part in the testing.

Let’s start by introducing what BDD is and what it can bring.

Introducing behavior-driven development (BDD)

When a new version of a software is released, we need to check:

  • Provided features match the expectations (specifications)
  • Absence of bugs
  • No regressions were introduced on existing features

Most of the time, a dedicated team is responsible for these issues and is designed by “Quality assurance” or “QA”. Wikipedia defines Quality assurance (QA) as:

This team is aware of the expected features at a functional level, i.e. what features must be provided from a user perspective. For this reason, this team isn’t necessary technical and aware of the technical issues.

Behavior-driven development targets this context. This article won’t dive into its concepts too deeply but the important things are:

  • Use of scenarios to describe what is tested
  • Use of a simple domain-specific language (DSL) using natural language constructs (e.g., English-like sentences) that can express the behavior and the expected outcomes
  • Acceptance tests and scenarios must be read by non-technical people

Such principles obviously apply to web APIs. The new version of Client extends its testing support to provide a BDD approach.

Getting started with the scenario-centric view

The view introduced in the latest version of Client focuses on tests and provides a dedicated web UI to display them efficiently. Throughout this section, we will get familiar with it.

Switching to the scenarios perspective

The first thing we’d like to show you is how to access it. This is very easy as two tabs were added right beside the Client logo on the top left corner:

  • Requests to access the default view to create and organize requests
  • Scenarios to switch to the scenario-centric view

The following image shows these two tabs:


Organizing your tests

Similarly to previous versions of Client, we can organize our requests and tests within the scenario-centric view using projects, services, and obviously scenarios. They correspond to containers for requests, even for other containers.

For example, a project can contain services and scenarios and a service, some scenarios.

02-add-container 03-add-container

Leveraging these containers is particularly interesting when your testing project becomes bigger.

Creating and navigating through requests

Once again, we won’t describe how to create requests but rather focus on new ways to create and navigate through requests within the scenarios-centric view. An effort was made at this level to make this easier.

First, from the menu, the + icon allows us to add a request at the end of the scenario.


A similar mechanism is implemented at the level of the request details to go to the previous and next requests if any. We can eventually add a new one if we display the details of the last request of the scenario.



Assertions remain the same but the scenario details page now gives a readable version of them. This is very useful if we want to share / exchange with less technical people of the team.


Executing tests

Within the scenarios-centric view, we can execute our tests at different levels. This feature is very useful to test either a subset of requests or the full scenario.

At request level. Imagine that we only want to test a particular request. Just go into the request details and click on the play button in the middle. Only this request will be executed in the scenario and we will see its result in isolation.


We need to be careful when using this mode since requests can be dependent. For example, a request that adds an element and another request that checks that the element was actually added.

At scenario levels. Restlet Client also provides the ability to execute in series the whole scenario. In this case, just go into the scenario details and click on the play button at the top.


Display errors

For both execution modes, Client gives you hints about the execution and if defined assertions are successful or not.


When we go a step further, at scenario level, things become a bit more functional and more human-readable. We don’t see anymore technical hints about the execution. That’s where BDD occurs. If we have a look at our scenario, we can see that the first request was correctly executed (in green) but the second was not (in red). So globally the scenario execution failed.

If we have a closer look at the second request, we can see an explanation with the format: When I do something then the assertion expression should be the assertion value / expression. This is what we expect. But, in our case, there is an additional “but” because our expectations aren’t achieved: the text after the “but” keyword provides some explanations.


A summary of the latest execution of requests and scenarios is also displayed in the left menu. This way, we can easily and quickly see what was successful and which requests failed. Leveraging navigation, we can move to a particular request to have more details about errors.


From the beginning of this article, we focused on the new feature of Client, the scenario-centric view. We dealt with its concepts and how to use it but it’s time to see the benefits when testing a real-world web API in action.

Real-world sample

The scenario-centric view allows us to see the complete scenario and read what will be tested. For this reason, in a real-world use case, it’s important to fill all descriptions.


For each item in the scenario, we can expand the description to see more about what we will be executed and tested.


The details about a scenario item allow us to display complex execution containing context variables and checks from the JSON response payload.


You can download this corresponding project here.


In this new version, Restlet Client brings the behavior-driven development into web API testing. This allows members of a same team (both technical and non-technical) to work together and exchange on the tests of a web API.

That being said, technical profiles can always switch to more low-level requests if necessary. Both views, requests-centric and scenarios-centric, are automatically synchronized.