Examine provides a simple but very effective REST testing support that can be used to test REST-based Web Services. The starting point for REST-testing is the REST project. A REST project is a collection of Resources where each resource represents a single HTTP endpoint accessible that can be invoked over a HTTP method like GET, POST, DELETE, PUT, etc. Each Resource can in turn contain sub-resources and acts as the parent of the sub-resource. The sub-resource itself is a valid REST Resource and the same rules that apply to resources also apply to sub-resources.

Consider the example of a REST-based sample Stock Quote Service that is available at the endpoint: http://localhost:9998/stockquote. We'll use this as the example to describe and demonstrate how to use the REST functionality going forward.

To begin, create a new REST project from the Projects screen. Click on the New Projectlink button to bring up the Create New Project dialog and select the REST option. Clicking on OK button brings up the REST resource creation dialog as shown below:


Specify a unique project name (e.g. SimpleStockQuote) and click on OK to create the project. If the Add new REST resource... checkbox is selected, then you can also create a REST resource immediately following the REST project creation. This brings up the Create new REST Resource dialog as shown below:


In the displayed dialog, specify the values of the following fields:

Once the REST project is created, clicking on the project name, displays the project details like Created and Modified date. REST resources which are created as direct children of the REST project are called 'root' resources. These resources are represented by the icon.

Root resources represent the top-level resource endpoints that can in turn contain many sub-resources under them. Each root resource contains a Base URL that captures the protocol, host and port information of the REST endpoint. To create a new root resource as a child of the REST project, right click on the REST project name and select Root Resource as shown below:

This brings up the same Root Resource dialog to specify the resource details as shown in this figure . Clicking on the root resource node in the tree view displays the resource details like this:


The details view contains Main, Request and Test tabs that can be used to configure the current root resource. The response tab displays the result of invoking the resource endpoint.

The Main tab contains the following resource configuration fields:

Base URL

This field represents the base URL of the resource. For e.g. value can be http://localhost:9998 that specifies the protocol (HTTP/HTTPS), the server name (localhost) and the port number (9998). The base URL will be common to all sub-resources that are created as child resources of this resource. This is also a required field.

Note

The Base URL field is editable only for the Root Resource. Sub-resources will automatically inherit this value from their parent resource.

Inherited Path

This is non-editable value that represents the path inherited by this resource from all its parent resource hierarchy. For root resources, this value will is empty (None).

Resource URI

This field represents the actual context path of the resource. In this example, it is set to /stockquote and the final resource URL will be http://localhost:9998/stockquote, which is a combination of the Base URL and the specified Resource URI.

The Resource Parameters button can be used to specify the values for any resource parameters specified as part of the resource URI. Please refer to this section on the different types of resource parameters for more information.

HTTP Method

This field represents the available HTTP methods that can be used to invoke this resource URL. The available methods are GET, POST, PUT, DELETE, OPTIONS, HEAD. It defaults to GET.

Content-Type

This field presents the available pre-defined content types that can be set when sending the request to the resource endpoint. The default set of values are as shown below.


If the content-type you would like to set is not available, you can click on the button to add a new content type to the list and select it.

Accept

The Accept field can be used to specify the value of the Accept HTTP header. By default, this value is */*, which means that there is no preference for the client in terms of the content type that the server should send the response in.

REST resources can have different types of parameters that make up the data portion of the request. This data can be sent as part of the request in multiple ways to the resource endpoint. Following are some of the different resource parameters that can be configured:

Header parameters are nothing but HTTP request headers that are sent to the resource endpoint. Please see the section on configuring the HTTP request for more information on how to send custom HTTP headers.

Other aspects of the HTTP request sent to the resource endpoint such as the HTTP headers, Authentication information or the SSL configuration if the endpoint is using the HTTPS protocol can be configured by clicking on the Request tab.

Every REST resource details view includes the Test tab that be used to configure the test case for that particular resource. This is useful when you want to assert some information in the response coming back from the resource endpoint. This functionality is similar to configuring a test case for SOAP scenarios.

The Test tab allows for adding assertions that execute on the REST response and verify the assertion requirements. The available assertions can be seen clicking on the Add button as shown below:


The Add to Suite link can be used to associate this REST test case with an existing Test Suite or a new REST-only Test Suite.

Available Test Assertions

The default set of available Test Assertions for REST resources as follows:

Assert HTTP Response Code:

This assertion verifies that the HTTP response code is a particular code such as 200 (OK) or 401 (Unauthorized)

Assert HTTP Header:

This assertion can be used to check if a particular HTTP header is present, absent or is equal to a certain value.

Assert HTTP Response time:

This assertion can be used to verify if the HTTP response was either less than or greater than a certain threshold value specified in milliseconds.

Assert Response Contains:

This assertion can be used to check for the presence of a particular token in the HTTP response. If the ‘Regular Expression’ checkbox is checked, then the specified text is used a regex pattern against the REST response body. The regex pattern should follow the Java regular expression rules.

Assert XPath Result:

This assertion can be used to check if an XPath expression evaluates properly against the REST response (if it is XML). Click on the ‘Configure’ button to open the XPath Expression dialog box where you can enter the XPath expression to use and declare the namespace URIs for any prefixes used in the expression.

Each namespace declaration should be entered on a new line and is of the form:prefix = URI

The result of evaluating the XPath expression will be a Boolean true/false. If the xpath expression results in DOM Nodes, then the result is True and if no there are matching nodes, the result is false. If the expression contains a predicate clause, then the result is either true/ false as well.

Assert XML Schema:

This assertion can be used to perform XML Schema validation of the REST response body contents. This is only applicable if the response is in XML format. To add XML schemas against which the response should be validated, click on the Configure button to open the XML Schema configuration dialog as shown below.

The Add button can be used to upload a single W3C schema (XSD) file or a zip file containing the root schema and its imports/includes as relative references within the same archive.

When the REST resource is executed, the assertions configured in the Test Case are verified against the response. The assertions that failed and succeeded are highlighted in red and green respectively as shown below:


loading table of contents...