Handling responses in the HTTP Client

At the HTTP client’s inception, we’ve been primarily focused on the composing requests experience, and PhpStorm 2018.1 brings numerous improvements in this area. Working with responses, however, has been greatly enhanced, too. Let’s resume where we left off, and take a look at it.

splash

Response handler scripts

In PhpStorm 2017.3, receiving a response from a web service was pretty much the end of the story: you could open the response file in the editor or compare the differences between such files visually, but no further automated processing was possible.

In PhpStorm 2018.1, we are introducing response handler scripts, which allow programmatically ‘reacting’ to a received response.

Response handler scripts are provided within the HTTP request file and can be inserted either in-place or by referring to an external file.

To provide the script in place, prepend it with > and enclose it in {% %}:

Of course, you may want to keep your response handlers in separate files: this will allow you to manage them easier and add them to VCS to share with the team, and so on. To use such external scripts, simply provide the path to the script prepending it with >:

Response handler scripts are written in JavaScript, with coding assistance and documentation handled by the bundled HTTP Response Handler library. For in-place scripts, this functionality is enabled automatically. To enable it in an arbitrary JavaScript file, invoke Use JavaScript Library and select HTTP Response Handler:

use_lib

The library is provided with the IDE and is managed under Settings/Preferences | Languages & Frameworks | JavaScript | Libraries. To get an overview of what’s inside, you can open it in the editor by invoking Go To Declaration on the client object in the response handler script.

Composing a response handler script

One of the common use cases for a response handler script is testing a web service that requires authorization. First, you capture an authentication token, and save it somewhere. Next, you use it in subsequent requests for web service authorization.

Let’s do just that, following the example request from the auth-requests requests collection. You can open it at any time via Tools | HTTP client | Open HTTP Requests Collection.

auth-request

The httpbin service that we use for testing purposes simply echoes what we’ve sent to it. This way, we can emulate the receiving of the my-secret-token authorization token in the HTTP response:

receive-token

As soon as the response is received, response handling is brought into play. In our case, we obtain the token field from the received response, and save it in the auth_token global variable so that it can be reused. We do this by means of the two objects exposed by the HTTP Response Handler library:

  • client stores the session metadata, which can be modified inside your script. Its state is preserved until you close PhpStorm, and all variables saved in client.global are accessible to subsequent HTTP requests as {{variable_name}}.
  • response holds information about the received response: its content-type, status, response body, and so on.

In our second request, we refer to the saved token as {{auth_token}} to perform authorization:

use-token

That’s it! By using this short response handler script, we’ve automated our workflow a bit: there’s no more need to copy and paste the token between requests and responses each time.

Assertions support

We are now capable of saving the response data and working with it granularly. Our next step will be to we verify the received data and make sure that it is what we actually expect to receive. This will allow us to use the HTTP client as a test framework.

To explore the testing possibilities, let’s pick a request from the test-responses requests collection:

assertion-request

Here, we perform a test as part of executing a response handler script. To create a test, we invoke the client.test(name, function) method; inside the test, we assert a condition using the client.assert(condition, message) construct: in our case, we extract the status field of the response object to verify that the server responds with the 200 status:

assertion-run-test

It looks like the test has failed, but we can easily find out what exactly went wrong. On the Tests tab of the Run tool window, we can see the error message as well as rerun a request together with the corresponding test.

With these new HTTP client features, it is hard to know where to draw the line: the possibilities are truly limitless. And bear in mind that our work on the response handling API has just started: we surely plan to further extend the possibilities of the client and response objects. What can you expect next? You tell us! Feel free to share your own response handling examples and favorite assertion styles, and stay tuned for more updates!

Your JetBrains PhpStorm Team
The Drive to Develop

This entry was posted in Cool Feature, Newsletter and tagged , , . Bookmark the permalink.
  • sciamannikoo

    With the GUI REST client, I can put a breakpoint in my code and debug the REST call by clicking the debug button instead of the run one.

    With the editor based rest client it looks like I don’t have this option, do I?

  • Greg

    Hi.

    I the concept of rest client but I see two limitations:
    – I would like to have ability to use some form of scripting on INPUT json – for example: i need to create something with unique email and it would be nice if I could do something like:
    {“email”: “user+{%time()%}@host.com”}
    – ability to run from command line to integrate with CI

    Are there any plans for those two? Should I create issue for them?

    • Maxim Kolmakov

      Thank you for your feedback!
      – That makes sense. Please create a feature request.
      – We’re planning to implement command-line tool that will execute requests without PhpStorm (on CI, for example) since a lot of our customers really want this functionality.

      • Greg

        Hi.

        if I can suggest something: use php to parse and process those files to integrate with CI – it will be fastest and easiest to do :) and very easy to integrate with PHP focused CI.

        Also making output compatible with phpunit output should be easy so it can be integrated with current PHPStorm UI for test running.

        Issue about scripting added: https://youtrack.jetbrains.com/issue/WI-41615

        Thank you and have a nice day.

        • Maxim Kolmakov

          We will probably provide a tool written in Java or Kotlin since these are our main developing languages and REST client is also included in our other IDEs (IntelliJ, PyCharm, WebStorm) and so on. So we will need to provide some language independent solution.

  • Leonardo Cidral

    how to use a global variable in a post body request?

    POST {{host}}/proposal
    Content-Type: application/json
    Cache-Control: no-cache
    Authorization: Bearer {{auth_token}}

    {
    “proposal_id” : {{proposal_id}}
    }

    > …