Tutorial 02 12 Postman Tests

Generating and Using Postman Tests

Postman is an application that is frequently used by web service developers to test their APIs; it allows them to fully interact with their HTTP-based web services, using all of the required HTTP methods, and working with things like custom HTTP headers, without the need to write code.

In Harmony Core development environments, if you have chosen to generate OData endpoints, then you also have the option of generating Postman tests for those endpoints that allow you to test them using Postman. This provides you with a quick and easy way of validating whether your APIs are behaving as expected.

Within Postman developers work within a Workspaces, and those workspaces contain Collections. Each collection is like a root folder within the workspace and is typically used to collect together the various Requests for a particular application or API. Within collections, you can optionally use folders to further organize your 'Requests' within the collection. Each Request represents a single HTTP operation. For example, a request may define an HTTP GET operation to a specific URL, perhaps the URL of your "get all customers" endpoint.

Developers can manually create workspaces, collections, folders, and tests, and can optionally export the information about those things to a JSON file that can be version controlled or shared with other developers.

When you enable the generation of Postman tests within a Harmony Core environment, we simply use CodeGen to generate a JSON file that has the same format as a Postman export file for a collection. The developer can then simply import this file into a Postman workspace to get access to all of the included requests.

Generating Postman Tests

To enable the generation of a Postman tests export file you must enable the ENABLE_POSTMAN_TESTS option:

1. Edit regen.bat and remove the rem comment from the beginning of the line, like this:

   set ENABLE_POSTMAN_TESTS=YES
   

Generating the Code

2. Save your changes to regen.bat.

3. If you don't already have a command prompt open in the solution folder, use the Tools > Command Prompt (x64) menu option to open a Windows command prompt, and type the following command:

   cd ..
   

4. Type the following command to regenerate your code:

   regen
   

As the batch file executes you will see various messages confirming which source files are being generated.

5. Look for the word DONE to indicate that all code generation tasks completed successfully.

What Changed

Having enabled this new option you will find that one additional file is generated in your main solution directory. The name of the file is:

PostManTests.postman_collection.json

Importing the Generated Test File

6. Start Postman.

7. Use the Import function (File > Import, or click the Import button near the top left corner of the applications) to load the tests into the UI ready for use.

Having imported the test file you should see a new Collection named Harmony Core Sample API. The collection will contain a folder for each entity type, and within each folder, you will find the individual requests that can be used to test each of the OData endpoints of your service.

Configuring Postman to Allow Self-Signed Certificates

The first time you start Postman you will need to allow communication with web sites that are using self-signed TLS certificates. To do so:

8. Select File > Settings from the Postman menu.

9. In the 'General' tab of the SETTINGS dialog, look for a switch control labeled SSL Certificate Verification and ensure that that option is turned OFF.

10. Close the SETTINGS dialog.

Testing an Endpoint

11. In Visual Studio, press F5 (start debugging) to start the self-hosting application. Once again you should see the console window appear, with the messages confirming that your service is running.

12. Back in Postman, under Collections, expand the Harmony Core Sample API collection, then expand the Customer Tests folder.

13. Select the GET Read Customers request.

This will open a new tab in the main body of the application, the title of the tab will be GET Read Customers and it should look something like this:

Just below the requests tab, you will see the HTTP method that will be used for the request (GET in this case), as well as the URL of the request that will be executed. The URL will look something like this:

{{ServerBaseUri}}/Customers

The {{ServerBaseUri}} part of the URL is a reference to a Collection Variable. If you edit the properties of the collection you will see that it is set to the base URL of your test service (https://localhost:8086/odata/v1). Using collection variables like this makes it easy to change the base URL of the service in one place, thus updating all of the requests in the collection.

14. Click the big blue Send button that you will see to the right of the URL.

Clicking the Send button makes Postman issue the HTTP request to your service, wait for and receive whatever response comes back from the service, parse that response, and display the details in the UI. The response should look something like this:

You will notice that within the main tab that represents the entire request, there are two embedded tab-sets.

The first tab-set contains tabs for Params, Authorization, Headers, Body, Pre-request Script, Tests, and Settings. This represents the REQUEST to the service.

The second tab-set contains tabs for Body, Cookies, Headers, and Test Results. This represents the RESPONSE from the service, and you will see that the body of the response contained the JSON data for all of the customers.

To the right of the response tabs, you will see a small section of UI that presents a summary of the status of the request.

Status: 200 OK   Time: 70 ms    Size: 13.95 KB

Requests Requiring URL Parameters

When we generate the Postman export file we insert sample values for the values of the various keys in some of the URLs, we use the value 123 for the value of numeric fields, and the value 'ABC' for the value of alpha fields. You will need to replace these values in the URL's of the various test operations before attempting to execute each test.

15. Click on the request Read Customer.

You will notice that this request requires that a value be passed to a CustomerNumber parameter, but the arbitrary value 123 has been inserted when the Postman tests were generated.

{{ServerBaseUri}}/Customers(CustomerNumber=123)

16. Click the big blue Send button.

You should find that the service will respond with an HTTP 404 (Not Found) response. This is because there is no customer with that customer number.

17. Change the parameter value from 123 to a valid customer number (between 1 and 38), then click the big blue Send button again.

This time you should once again see a 200 OK response, and you should see the data for the customer that you requested.

Stop the Service

18. When you are done with your testing, stop the self-hosting application.

Learning Postman

This is only intended to be a very brief introduction to Postman, which is an extensive and powerful tool. We recommend that you learn all about the application and how to use it. Here is the Postman Documentation.

---

Next topic: Supporting CRUD Operations

---