Restlet Blog

In our previous blog post about DHC, we introduced the foundations of the tool. But DHC isn’t just a tool to execute HTTP requests, it also allows you to apply some rules on calls to check that the responses received correspond to what is expected.

Assertions

The foundations of testing in DHC correspond to assertions: a way to determine if calls match what is expected to be returned by the API under test.

Defining assertions

For each request an Assertions tab is provided to define the rules that the response of a call, to a RESTful service, needs to check to be successful.

An assertion consists of several parts:

  • The part of the call the assertion applies to. The following parts are supported by DHC: status, header, JSON body, body and response. You can see that there are two “body” parts. As a matter of fact, the tool provides native support of JSON within body. This means that you can leverage JSON Patch to get data from JSON content.
  • An optional parameter depending on the previously selected element. For example for headers, it corresponds to the name of the header.
  • The comparison to use. The matching mode can differ depending on the part of the call. Of course, standard comparisons (equality, superiority, inferiority) are always present. In addition, where header and body is concerned you can also check existence and containment.
  • The value to check. This can be raw values but also expressions.

The following screenshot provides a sample use of assertions within the Assertions tab:

dhc-test-17

If at least one test fails, the call is flagged as failed. In the same spirit as xUnit tools in different languages, DHC uses the green color for successful assertions and the red one for failures.

You’ll notice the ability to disable assertions if necessary using the checkbox right before the line of the assertion, as shown below:

dhc-test-14

As you can see, the assertion that failed isn’t taken into account anymore.

Now that you’ve seen the basics about assertions, let’s dive a bit more into the power of DHC to define the response element to test.

Testing response parts

The first part is obviously the status one. In this case, you can choose not only the status code but the status message as well.

dhc-test-04

Regarding response headers, DHC allows you to check both their presence and their content. In the first instance, you can simply put the name of the header in the parameter field and use the comparison “Exists” or “Does not exist”, as shown below:

dhc-test-12

Checking the header value is pretty simple, just change the comparison to ‘equals’ or ‘contains’ for example and fill the value field with the expected value.

dhc-test-06

Just as you do  for headers, you can also check either the presence or content of a payload. The first case is interesting for responses with empty payloads, typically with status code 204.

dhc-test-20

For text-based payload, structured or not, it’s possible to check if the content matches to a specific value, or contains some text, as described below.

dhc-test-16

Testing text payload can be tedious if they are only considered as text. For this reason, DHC goes further by natively supporting JSON body. The latter allows to apply specific JSON path expressions. We will focus on this feature in the next section.

Before diving into JSON payload, don’t forget the support for the response itself. This allows you to apply assertions to its latency. This is particularly useful if you want to test the maximum time for a call.

dhc-test-01

Using JSON path for JSON payloads

When selecting JSON body, assertions can leverage JSON path expressions to use and check specific parts of the content. Stefan Goessner provides a great introduction in his article JSON Path – Xpath for JSON. This expression language is natural and enables you to browse data graph easily.

Here are the main elements:

  • The starting point is the expression “$” that identifies the root object of the JSON content. Then you can iterate over attributes and sub attributes. The language natively supports arrays.
  • The point allows you to get an attribute of an object. This can be done recursively according to the depth of the data graph.
  • The square brackets target arrays and allow the selection of a particular element in them.

The following sample describes how to test the value of a list contained in arrays. The JSON body used contains a list of maps, each map has a ‘sources’ field. This field corresponds to a list of sources and has an id attribute. The expression $[0].sources corresponds to the sources of the first element. The expression $[0].sources.id goes further by getting all the id fields of sources. It’s then possible to get just the first one.

dhc-test-21

Notice that the value to check can be valid JSON content. DHC automatically parses it and checks if it matches with the content corresponding to the expression. The following sample describes how to check the content of an array.

dhc-test-07

Leveraging expressions in assertions

Now we know how easy it is to define assertions and check different parts of calls. However DHC goes a step further as you can take advantage of expressions in assertions.

Imagine that you have settings in your context e.g.  the ‘contentType’ you want to use for exchanging data (both request and response).

dhc-test-15

You can then use this variable when defining your request in the Accept header, to tell the RESTful service that you expect JSON content. To test this behavior, you can add an assertion to check the content of the Content-Type response header and to be sure that JSON content is actually received.

dhc-test-05

Another possibility is to rely on the result of previous calls. DHC lets you reference the executed calls through expressions. For this to be possible, these calls need to have been saved at least once. The tool will automatically look for the corresponding last call in the history. To do this, it is important to follow this pattern: {“PROJECT-NAME”.”SERVICE-NAME”.”CALL-NAME”}. You can then reference any part such asresponse body or headers. For example, to get the value of the id attribute in the response body, simply use the expression response.body.id, as described below.

dhc-test-09

We’ve covered the various capabilities of DHC by Restlet regarding testing. In our next installment, next week, we’ll apply this knowledge to a real-world RESTful service! Please stay tuned!

2 Comments

  1. Pingback: Testing a real-world RESTful service with DHC by Restlet | Restlet - We Know About APIs

  2. Pingback: Save your DHC test scenarios to the cloud and share them with your team | Restlet - We Know About APIs

  3. How to construct correct assertion if the response consists of an array of JSON objects, the order of which can be different between calls? For example I get the list of companies, and want to assert that 3 company names exist in the response, but they always come in different order. So my assertion $.compName Equals [“All Electronics”, “Daka90”, “Texas Steak House”] fails in some test runs and succeeds in others.

  4. Filip Kolarik

    Hi Ivan,
    thank you for sharing your use-case. DHC doesn’t support a comparison of unordered arrays yet, but it’s definitely on our roadmap.

Leave a Reply

Your email address will not be published. Required fields are marked *