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.
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 {% %}:
GET host/api/test
> {%
// The script goes here
...
%}
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 >:
GET host/api/test > tests/myTest.js
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:
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.
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:
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:
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:
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:
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
Subscribe to PhpStorm Blog updates
