• You should have a nodding acquaintance with the HTTP comprehending what the request and response consist of.
• You should understand the principles of a query construction for a service resources access and what REST API means.

Introduction

SoapUI is a tool for Web Services testing that based on work with HTTP.  There can be services which API is built upon the REST methodology or the SOAP protocol. Developers and QA engineers use this tool for automated functional, load, regression tests and many other things. SoapUI is considered the richest software tool of a kind in terms of functionality. Launching this program for the first time you don’t know where to look first as you don’t understand where to start. However, the range of its opportunities and its utility are being realized when you dive back into it and work for a while.

In this article I would like to assist newcomers to take the first step towards getting acquainted with this powerful tool from scratch, from its installation to creating your first HTTP request to a REST service and to its coverage by tests. Here we go!

Installation

SoapUI is a cross-platform program that is available in two formats: Open Source и Pro. To complete everything that will be covered in this article the Open Source version functionality is enough.You can download an installation file for Windows, Linux, MacOS on the developer official website https://www.soapui.org/downloads/latest-release.html.

There are some key steps for the installation on the 64-bit version of Linux:

• firstly it’s necessary to install JRE
• download an archive with the program
• extract the installation file into a catalogue
• make sure that a user on behalf of which a launch is performed has the rights to read and write to the directory
• enter the catalogue, grant rights to run a file bin/soapui.sh
• The next step is an optional one. Create a  run app shortcut following the steps listed in a guide from another article “Your First Postman Test”.

As for other software systems it’s quite easy. Suffice to download the installation program, run it and follow its simple instructions. If any issues have been noticed during the installation process you can refer to the detailed manual and a relevant section of documentation to find a solution.

Interface overview

Launch the program. There you can see the following interface components:

• a project console (on top). There are buttons for a project creation, import of a previously created project, save, a link to a community forum, SoapUI app settings, and quick switching off/on of a run queries through a proxy server.
• a project navigator (on the left). A project tree is displayed here you can add, delete, disable nodes of different purposes (Project, API server scheme, test cases, and etc.).
• a properties window of the chosen node (bottom left). Depending on the node selected in the navigator, tables with various sets of properties for their quick editing are displayed in the window.
• a primary workspace is located to the right of the navigator, there editing and running all the project tree elements happen.

Creating a project and an API scheme

By default the navigator has a Workspace node, in which nodes of a Project type are grouped. You can create a project draft through the app menu File > Create empty project by clicking a relevant button in the project console or through a context menu of the Workspace node in the navigator.

To create any RESTful service query in SoapUI you first have to create a WADL(Web Application Description Language) element in the project, in which resources and accessor methods to them through the web service interface are described. There is an opportunity in SoapUI to import an API scheme from Swagger, open an already prepared scheme or create a new one from scratch. So let’s create a scheme from scratch.

I use one of the many free API’s as a guinea pig. Let’s create a GET request at URI as an example https://hacker-news.firebaseio.com/v0/item/8863.json?print=pretty. You need to choose New REST Service from URI through the context menu of the created project in the navigator. Enter our URI in the dialog box. Four nested nodes are created in the tree. We’ll sort it out what is what.

The top level element is the entire WADL scheme. If you open this node by a double click you can see the navigator window and description of the scheme in the WADL language (derived from XML) in the appeared window on the WADL Content tab. In the settings of this nodes on the Service Endpoints tab you can list various hosts names on which running this service. There is already one host name that the program has derived from the input URI. Let’s imagine that we are developers of the service and want to test a new functionality on the test server (for example, a fictitious server is https://stage.hacker-news.firebaseio.com) and keep an eye on our realised server. In this case you need to add one more record into the endpoints https://stage.hacker-news.firebaseio.com. Now we have the opportunity to choose on which server we will run the prepared test cases.

The next element named 8863.json [/v0/item/8863.json] has the form of one of many service resources description. In this case a type of resource is an item, and 8863 is an identification number of a concrete instance of this type. You can specify a path to the resource on the server in the edit window for this element and add a number of parameters and headings with which any requests to this resource should be made.

On this step, I would like to add a bit of Feng Shui in the scheme description and  make this resource more universal. In the program generated path to the resource, requests can only be made to the instance with the ID 8863 in json format. Let’s assume that there are more instances on the server than this one and they can be implemented in XML format. To make description of the resource more useful you should rewrite the path to it having applied template parameters:

You can create queries to this resource in a such way transferring instance ID item_id and its format format ( json by default) as a parameters.

The following element defines available query methods to the resource. In the edit window for the element you can choose method type and add various query parameters specific to requests when accessing a resource through this method. You can add many queries to a such node on the navigator tree. Each of them is able to extend a number of parameters and assign a specific value. The program has generated GET method from the previously input URI. This is exactly what we need.

Well, finally, we give consideration to an element of the request itself. In this component you can directly run a query to a service on one of the endpoints, defined in WADL, for an access to the resource through the chosen method. In the left part of the element settings window you can notice a table with all sorts of query parameters that are inherited from a resource and method. On the Raw tab there is a submission of a request in accordance with the HTTP protocol. You can behold server response in the different formats in the right part of this element window. SoapU parses server responses and provides them in more convenient to perceive format than if it is in a raw HTTP.

Separately I would like to emphasize that resource and methods are part of the API Web service scheme description while queries are abstraction of the SoapUI itself, and it is not mentioned in WADL scheme. You can verify it returning to the WADL Content tab.

Sending HTTP requests

To make a request you should push the button as an Play icon in the upper left corner of the request box or you can avail of Alt+Enter shortcut.

Server has returned a response status with error. What is it, then? Let’s consider the Raw HTTP request:

GET https://hacker-news.firebaseio.com/v0/item/.json?print=pretty HTTP/1.1

Accept-Encoding: gzip,deflate

Host: hacker-news.firebaseio.com

Connection: Keep-Alive

User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Great! Your first successful request in SoapUI has just been made. Please pay attention that depending on Content-Type in the response the program provides relevant submissions for a human readable perception of information. In this case you can find response body with its marked format on the JSON tab.

Writing test cases

We have learned to make query to a Web service so now it is time to cover it by tests. We can generate test cases for each of our resources by selecting Generate Test Suite through the context menu of the WADL element in the navigator. However, I’d rather make it step by step on my own.

So we add a Test Suite object in our project through the context menu or using Ctrl + T shortcut. Then we should name it Item Resource TestSuite. In the TestSuite settings menu we are able to detect a list of TestCases, controls for launching and pause of tests of this group, choose serial or parallel way of launching, set description on the Description tab, set variables that are common for all tests of the group on the Properties tab, write a script in Groovy that will be completed before running and at the end of all tests for test environment setting.

Criteria for cases integration in TestSuite can be various. This can be tests aimed at a particular part of service functionality coverage, tests aimed at Quick regression testing, tests for different parts of service functionality monitoring, and other. In our case that is not an issue that’s why I will add in prepared Suite only tests connected with an access to item resource.

Let’s create a first test case through the TestSuite context menu or using Ctrl + N shortcut. Then we should give a meaningful name expressing the coverage of the test for short, Should return requested item. Because of the test case name it is clear that we would like to make sure the object request service with the given ID should return relevant resource data. There are elements for starting and force trip of a case, case circularity option, service authorization method setting, choosing endpoint on which this case will be running, button for adding load and vulnerability tests in the TestCase edit window. Next is progress bar of a test case implementation and a list of its steps.  

Test case can consist of many different steps, and one article is not enough to consider their diversity. That’s why I will concentrate only on one that is handy for us. Press the second button on the left with adding a step “Create a new REST Request TestStep”.

Then we should name it as a “send request” and in the appeared dialog box with the list we choose one of the previously created requests.

Now our test case has the first and only step. Further, we need to add “face-to-face” checks of the request results. At the bottom of the TestStep settings window (by the way, this window is very similar to the request settings window) you can find Assertions tab. This is where all conditions for this step check are added. Let’s bring in an assertion to verify that a returned response complies with a requested item:

• Click on a button with the “+” icon;
• Choose JSONPath Match snippet in the appeared window in the Property Content section;
• Write a path to the ID field in a response: $.id in JSONPath Expression;
• Write the value 8863 in the Expected result field.

Then we should run the step as we run request. This step icon in the navigator tree has become Green as well as Assertions tab. Great, this is success!

Frankly speaking, our test is of very low value and it is quite easy to break it. Let’s make a duplicate of the TestCase using F9 hotkey or through the context menu and change the item_id value to 9224 in this step.

Having run this step, it will become red in your test. Logically, the server has already returned the object with other ID. Now we have to amend the assertion description. We will specify a current step variables – ${item_id} as an expected result. Then, whatever item_id for the request we input our tests are always green. In SoapUI it is possible to indicate a link to any property value of any project element as value.

Running some tests

Let’s come back to our TestCase object. We have two steps in a list. TestCase instance implies step by step implementation. If any step has not completed its tests other steps will not be launched. Another situation happens with TestSuite. Here TestCases can be launched both in series or on parallel. If one of them has been failed other cases will be started or will not be interrupted. anyway. Let’s run our TestCase.

Everything is green. On the TestCase Log tab you can see the launched steps sequence and how much time their execution with verifications has taken.

Conclusion

In this article we have got familiar with SoapUI, the tool for writing automated tests of Web services, and with its basic functionality, learned to create an API Web service scheme, figured out what is WADL comprised of. Moreover, we have created our first request to an open API and covered it with the simplest tests without writing a single line of code.  In SoapUI there is an opportunity to make a query even easier just create TestCase with HTTP Request step. However, in this article I have decided to show how SoapUI differs from tools with similar functionality. I would like to say in the end that there are many more ways of making queries, cases and tests than I have been able to cover. SoapUI undoubtedly helps to improve the quality of a developing product, helps QA engineers as well as developers reducing the number of routine work. The project structure encourages good systematization of test cases and allows to run verifications of a large and complex system functionality parts.

Materials

File of the SoapUI project committed within this article: https://drive.google.com/file/d/1DwQpxAy9RTJ1qxxs5VjDzUu_j54xSBfQ/view?usp=sharing

Basic Auth

Let’s start with the simplest (and less common) method. It is quite rarely used (I used it a couple of times to restrict access to staging environment), definitely has some security issues, and shouldn’t ever be used without https. The thing is that for authorization (here we consider the option when we send the authorization data in a request header) we send username:password strings to the Authorization header base64. That means for a Postman user with a password ‘Password’ the string is postman:password and its base64 version is cG9zdG1hbjpwYXNzd29yZA==. Our data header will look like this:

Authorization: Basic cG9zdG1hbjpwYXNzd29yZA==

Note that base64 is not an encryption or hash algorithm. It is a data encoding algorithm, and that explains its low security level. Now let’s see how Postman works with basic auth using an example from postman-echo.

While choosing Basic Auth from authorization list you are prompted to enter your username and password. Just enter ‘postman’ and ‘password’, and the request willl be successfully sent 🙂 Postman encodes data to base64 and inserts it in the appropriate header:

Bearer token

Let’s now talk about bearer token. This is one of the simplest authorization methods. To send an authorized request, we need to pass the value Bearer <token>, where <token> is some character sequence (usually a hash) that is generated in response to a successful authorization. It looks like that:

Authorization: Bearer 129dabaf157205b46e393ce3e7f34ac6

Bearer token was developed as a part of OAuth 2.0 in RFC 6750, but it generally functions as an independent authorization method.

Now I’ll show you how to use bearer token in Postman. First, you find it in the authorization methods list:

Then you’ll be asked to type the token that I’ve mentioned earlier.

As you can see, Postman recommends you use variables to keep tokens secure. In some cases this also might come in handy – with the help of variables you can easily use the same token in different requests.

Digest Access Authentication

The first version of digest access authentication was described in RFC 2069. That is a standard version of this authorization method, which often doesn’t provide the required security level. Later on RFC 2069 was replaced with RFC 2617, where a range of measures for security enhancement were introduced. Postman supports this standard. Let’s explore it with an example from postman-echo.com.

Client-server interaction with digest access authentication includes:

1) Sending a request to the node that requires authorization. We get 401 (Unauthorized) code in response with digest access authentication parameters (or directives, according to the standard) in the WWW-Authenticate header. Here is an example:

WWW-Authenticate: Digest realm="Users",

                         nonce="Cmv5um4yl1wUrakLZhEH5FQpGA78EkkQ",

                         qop="auth"

2) Entering a login (username) and password (password) by the client (postman and password in our case). Here we just let the digest magic happen 🙂 No need to go into details since it’s all been thoroughly described in the standard. In short, the main thing here is calculation of the response directive using the chosen algorithm (MD5 or MD5-sess), the data that the client has, and the data that the server returned after step 1.

In the request all authorization parameters are passed in the Authorization header. The header will look like this:

Authorization: Digest username="postman",

                      realm="Users",

                      nonce="ni1LiL0O37PRRhofWdCLmwFsnEtH1lew",

                      uri="/digest-auth",

                      response="254679099562cf07df9b6f5d8d15db44",

                      opaque=""

It’s time to put theory into practice. Set the following request parameters in Postman:

• Request Type: GET
• Authorization Method: Digest Auth
• Username: postman
• Password: password

Realm and Nonce values come from the server, so we use variables mechanism and pass echo_digest_realm and echo_digest_nonce values to these directives respectively. That’s how our configured request looks like:

Now try to send the request and enjoy code 200 🙂

OAuth 1.0

OAuth 1.0 is an authorization protocol to access a third-party API. You probably use this authorization method from time to time while logging into some websites with Facebook or Github.

There are 3 parties in this authorization method:

1. Server. In fact, that is your application itself
2. User. A user of your app
3. Service Provider. A third-party service, which user data we’re trying to get access to (with user’s consent for sure)

Let’s imagine we want to retrieve the user’s social network contacts. Simply put, to do it we should follow the steps:

1. Send a request to the Service Provider to get a Request token. In the request we pass oauth_consumer_key (a key that identifies our server), oauth_timestamp (a timestamp), oauth_callback (an address where a successfully authorized User should be redirected to), oauth_signature_method (a digital signature type, that can take values HMAC-SHA1, HMAC-SHA256, and PLAINTEXT), and oauth_signature (a digital signature). Check out the standard to learn more about signature process. Please note that apart from request data, the Consumer Secret is also used – a key that only the Server and the Service Provider have access to. The Service Provider returns oauth_token (the very Request Token) and oauth_token_secret in response.

2. Redirect a User to the Service Provider authorization page. Here the User signs in and authorizes the Server to access protected resources. Then the Service Provider redirects the User to the address written in oauth_callback (step 1) with oauth_token and oauth_verifier parameters.
3. Using previously received oauth_token, the Server requests an access token. This is quite similar to the process of obtaining the request token, but for signature generating we use oauth_token and oauth_verifier from the previous step and ignore the oauth_callback parameter. The Service Provider returns oauth_token (our Access Token) and oauth_token_secret in response.
4. Send a request to get our User’s contact list, using the Access Token.

Let’s see how this authorization method works in Postman. Postman has the necessary field set, it can pass the authorization data both in query parameters and in the authorization header, and also calculates a digital signature automatically depending on the chosen signature generation method.

Let’s use our favorite postman-echo for testing. This resource provides the endpoint for signature verification (as you see, this is an essential part of this authorization method).

Create a new GET request on https://postman-echo.com/oauth1 and select OAuth 1.0 as an authorization method. Put RKCGzna7bv9YD57c and D+EdQ-gs$-%@2Nu7 values in the Consumer key and Consumer Secret fields respectively. As one can notice, the “Add authorization to” field allows you to choose where to add the authorization data. This is how the request looks like if we send the data using query parameters:

If you do it right, the Service Provider will report that the signature verification was successful.

If you already have an access token, you can type it in the corresponding authorization parameters field and send your requests to the authorized part of your application.

Conclusion

In this article we’ve discussed several authorization methods. In terms of authorization, Postman is much more powerful though. OAuth 2.0, Hawk and some more specific authorization methods are left aside today. Well, that’s a nice reason to get back to this topic one day, isn’t it? 🙂

Postman is a tool used by both client/server applications testers and developers to interact with API. Having appeared as a tool for sending simple requests, Postman has now drastically increased functionality, being able to deal with much wider range of tasks. However many of its features are “hidden” due to historical reasons and product positioning. This article is here to shed light on one of those features, namely requests testing.

Postman Installation

Postman is available as a native application for Windows, Linux and MacOS operating systems. Check out the link to download your version (https://www.getpostman.com/apps).

If you are a Windows or MacOS user, just run the installer and follow the instructions. The Linux version comes as a tar.gz file, so you need to:

1. Unzip the file.
2. Create a desktop file (optional). This will let you run Postman by double-clicking the icon and identify the app in different application launchers including system ones. Create a file by name Postman.desktop in ~/.local/share/applications with the following content:

[Desktop Entry]

Encoding=UTF-8

Name=Postman

Exec=YOUR_INSTALL_DIR/Postman/app/Postman %U

Icon=YOUR_INSTALL_DIR/Postman/app/resources/app/assets/icon.png

Terminal=false

Type=Application

Categories=Development;

YOUR_INSTALL_DIR is the path to the folder where Postman executable is stored.

Running Postman

Now you can find Postman in application launchers. Once you have Postman running, you can sign up on https://www.getpostman.com/ and sign in the app or ignore this step. Note that authorization allows to synchronize your data that might be helpful while working in a team.

In Linux-based systems there are a few issues you should pay attention to:

1. Don’t run the app as root This might cause some problems in further using of application (especially for unprivileged users).
2. Make sure the running user has read/write permission for ~/.config folder. This is where Postman stores the data.
3. Ubuntu 18 users will need a libgconf-2-4 package. It was removed from default Ubuntu packages, but may easily be installed by the command

sudo apt-get install libgconf-2-4

Interface Overview

Let’s take a look at the request interface. We’ll need it for writing the test in the future. The main purpose of Postman, as mentioned above, is to perform HTTP-requests. That is why the request interface is the first thing we see after running the app.

The top bar contains URL and request method (GET, POST, PUT, PATCH, etc.). Click the Params button to set the request parameters.

You can see several tabs just below. Let’s take a closer look at them.

Authorization. This allows to configure authorization methods for the request. Postman has an impressive list of the most common authorization methods. We are not going to change this parameter, thus we won’t focus on it and just move on.

Headers. As the name implies, this tab allows to change the request headers list. A very useful feature is the autocomplete menu both with header names and values list. However the list of autocompleted header values is limited to the content types list only. In fact the value set doesn’t depend on the header name, that may eventually lead to errors.

For headers editing you can use either spreadsheet-style edit mode (Key-Value Edit) or text edit mode (Bulk Edit). Unfortunately, there is no autocomplete feature here, but if you have a headers list in a special format (for instance, task description from bug tracker), this mode comes in handy.

Body: This tab is available for some methods (GET in particular) and allows you to add the request body. The request body interface is quite similar to the request header editing interface but still has its own features.

1. You can set the required content type choosing from form-data, x-www-form-urlencode, raw, and binary types. Those types, except for interface part, influence on Content-Type header.
2. Every type has a description field. That is quite convenient, you can make something like API description.
3. The field value can be either text or file.

If you choose the raw request body type, you can edit the request body in a raw form – the very body that is going to be sent to the server. This is not so useful, but having set the appropriate Content-Type header, we can edit the body with syntax highlighting (xml, javascript, json or html).

Request Sending

Let’s send our first request. For the experiment I’m using one of numerous free APIs – https://github.com/HackerNews/API. Here you can find an example of a GET request https://hacker-news.firebaseio.com/v0/item/8863.json?print=pretty.

That’s a typical GET request with parameters. Now let’s dig into response parameters tabs, that are at the bottom of the screen.

The Body tab contains the response body. As you might have noticed, highlighting can be changed here. But in most cases you won’t have to do that – it is set depending on the Content-Type response. You can also view the response body with no highlighting in Preview mode. This mode is helpful while viewing rendered content of an HTML response.

And the last thing we haven’t discussed on this tab is the line break button. As you can guess, it enables breaking long lines.

Cookies tab is unavailable here since this request doesn’t contain any cookies. We’ll get into Cookies tab features next time.

Headers tab is quite reserved. No mode changing, no highlighting. Just a key-value list.

We have dived in the basic Postman features to deal with HTTP requests, which can help us in testing. At the same time we’ve left behind some exciting ones as variables, environment, collections, etc. It has already been said that Postman has become something more than a simple tool for sending requests. And that’s not only about tests, if you just have a look at that New drop-down menu.

This truly is an impressive list.

Writing tests

Finally, we are here to create our first test. You can find the test editor under the Test tab of the request builder. Simple as that – there is an edit box on the left and snippets list on the right. Snippets allow to create test templates and help inexperienced testers in their work, but software development skills are highly important with Postman as all tests are written in JavaScript.

In our case, we need the snippet ‘Response body is equal to a string’. Choose that and Postman will generate a test template.

pm.test("Your test name", function () {

  var jsonData = pm.response.json();

  pm.expect(jsonData.value).to.eql(100);

});

var jsonData = pm.response.json();

Convert the response from JSON to JavaScript object:

pm.expect(jsonData.value).to.eql(100);

Check if the value received from the object is equal to 100. That’s pretty much it, we only need to add our data to the test. Change the last line to:

pm.expect(jsonData.id).to.eql(8863);

Here we check if the id of the received object is the same as requested id (8863). Now you see, there’s no problem with writing a test having all those snippets ready to help.

Resend the request to run the test. Now we can see the results of our test on the Response panel under the Test tab.

Congratulations, the test “Your test name” was successfully run!

And what if it wasn’t? Let’s change the id to irrelevant one:

pm.expect(jsonData.id).to.eql('wrong id');

After sending the request Postman says that your test failed:

Conclusion

In this article we’ve discussed basic features, that help in writing tests. Unfortunately, JavaScript skills are essential for working with Postman. To this end, Postman loses the game to SoapUI. However, snippets make things easier. Besides, the language is quite easy to learn (as compared to built-in Groovy in SoapUI). Anyway, automation tests is a new step in testing, and using this approach you can significantly increase the quality of your product.