Documentation

Add target host

Adding a target host is pretty easy. All you need to do is to navigate to Profile -> Target Hosts and to add your own host. Please note, you have to add domain with protocol (http or https): https://www.my-domain.com

After adding it you have to verify your host. You will find an explanation on how to do it directly after clicking the verify button. Only verified hosts can be used for testing.

How to write tests

Let's start with a simple example of how to write tests for endpoints. Imagine we have a rest endpoint that looks like this one:

REQUEST:
GET https://myapp.com/api/v1/articles/45

RESPONSE:

					

With this test, we’d like to confirm that the response payload is as we assumed above. That means that the data about the article has to be nested within article node. What we also expect is that the article has the id 45, a name and a price. However, the value of them is not important; we just want to make sure they are delivered. In that case our test looks like this:

{
  "tests":[
    {
      "name":"Test article endpoint",
      "test":[
        {
          "type":"request",
          "url":"$HOST[0]$/api/v1/articles/45",
          "method":"GET"
        },
        {
          "type":"assertion",
          "assert":["equals","200","str($[0].RESP.STATUS$)"]
        },
        {
          "type":"assertion",
          "assert":["equals","45","str($[0].article.id$)"]
        },
        {
          "type":"assertion",
          "assert":["not-equals","%null%","str($[0].article.name$)"]
        },
        {
          "type":"assertion",
          "assert":["not-equals","%null%","str($[0].article.price$)"]
        }
      ]
    }
  ]
}

As you can see, the json file starts with a tests node which is a list of possible tests in the file. Each test constists of a name and test node. The value of the name node is a test title which describes what you are testing. The test node is a list of components. In our example we can see 5 components representing only 2 different types. The first component is a type of request and the other four are a type of assertion.

In the component of a request type we also have a url which presents the endpoint that need to be tested and method which is in our case GET. You probably noticed $HOST[0]$ in the beginning of the url. This is a variable that gets injected into a file, and it's one of the targeted hosts we added in the first step, but more about that a bit later.

So now, we have four assertions. The first one checks if a status code of the response is 200. A prefix $[0] of the $[0].RESP.STATUS$ means that we would like to check a response code of the first request. Indexing of the requests starts from zero, which means, zero is a first request, one is the second etc. If we had a second request and wanted to check a status code of the second one, it would be: ["equals","200","str($[1].RESP.STATUS$)"]

The second assertion checks that the id of the article is 45. A prefix $[0] also indicates that we do an assersion of the first request.

The third and fourth assertions check if the payload of the response contains the nodes name and price in the article node. We expect them to be different from null which means they need to be delivered. We don't check a value here; they can be anything, even an empty string. If we wanted explicitly to check that is not an empty string, we would write: "assert":["not-equals","","str($[0].article.name$)"].

Function str() in the assertions indicates that the assertion value needs to be a string. For now, only string assertions are allowed. If we have a number like in our example (id: 45) it has to be asserted as a string (above example).

Let's imagine our rest endpoint requires authentication before we get the result. That means we would need to make 2 requests: the first to authenticate, and the second to get list of all articles. In the second request we also need to send the access token we got as a response from the first request, which looks like this:

REQUEST 1:
POST https://myapp.com/api/v1/auth

						
RESPONSE 1:

						
REQUEST 2:
GET https://myapp.com/api/v1/articles
Header: "Authorization: 256d211d585c4929a0d01f9549848b9c"

RESPONSE 2:

						

As we see here, we need to execute 2 requests, first for obtaining an access token and the second to get articles. There is our json file:

{
  "tests":[
    {
      "name":"Check get articles endpoint",
      "test":[
        {
          "type":"request",
          "url":"$HOST[0]$/api/v1/auth",
          "method":"POST",
          "body":{"username":"usr", "password":"pass"}
        },
        {
          "type":"request",
          "url":"$HOST[0]$/api/v1/articles",
          "method":"GET",
          "header": {"Authorization": "str($[0].accessToken$)"}
        },
        {
          "type":"assertion",
          "assert":["equals","200","str($[0].RESP.STATUS$)"]
        },
        {
          "type":"assertion",
          "assert":["equals","200","str($[1].RESP.STATUS$)"]
        },
        {
          "type":"assertion",
          "assert":["equals","2","str($[1].articles.#$)"]
        },
        {
          "type":"assertion",
          "assert":["equals","70","str($[1].articles.1.id$)"]
        }
      ]
    }
  ]
}

The last two assertions assert the list of articles. The first asserts that there are 2 articles as a response, and the second says that the id of the second article is 70.

How to execute it

After downloading the CLI from the website, an execution is easy:

./apitesting -s <service-token> -p <file_path.json> -h <your-domain>

An example is shown here:

./apitesting -s c58eae2dc7e207bc1aad190738e620 -p my_file.json -h https://myapp.com

In this case, our host to be tested is https://myapp.com and that's the one which will be injected as a $HOST[0]$ in our example above. Service token is available at: Profile -> Service Token.

The CLI tool makes an execution locally and as a response prints how many tests failed and the info about them.