Skip to content

Tutorial 02 12 Postman Tests

Jump to bottom
mattl91 edited this page Mar 2, 2023 · 9 revisions

Harmony Core Logo

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 the required HTTP methods, and working with elements like custom HTTP headers without the need to write code.

VIDEO: Creating a Basic Solution

In Harmony Core development environments, if you choose to generate OData endpoints, you also have the option of generating Postman tests for those endpoints. These tests provide a quick and easy way to validate whether your APIs are behaving as expected.

Within Postman, developers work within workspaces, and those workspaces contain collections. Each collection is like a root folder within the workspace and is typically used to collect 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.

Harmony Core Logo

Developers can manually create workspaces, collections, folders, and tests, and can optionally export the information about these 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, CodeGen generates a JSON file that has the same format as a Postman export file for a collection. You can then simply import this file into a Postman workspace to get access to all included requests.

Generating Postman Tests

To enable the generation of a Postman tests export file, you must set the Enable Postman test generation option:

  1. At a Windows prompt, move to the directory with your Harmony Core solution, and type harmonycore gui. Then, when the GUI for the Harmony Core CLI tool opens, go to the OData screen, scroll down to the Enable Postman test generation option, and double-click it.

  2. In the "Enter new value" screen, click the diamond icon to the right of Enable Postman test generation. (The diamond will change to a checkmark.) Then click OK.

Generating the Code

  1. Save the settings you made by selecting File > Save from the menu.

  2. Generate code for your solution by selecting Codegen > Regen from the menu. When code generation is finished, a message lists the files that were generated. Click OK to close the message.

What Changed

Two additional files are generated in your main solution directory:

  • PostMan_ODataTests.postman_collection.json
  • Postman_LocalDevelopment.postman_environment.json

Importing the Generated Test and Environment Files

  1. Start Postman.

  2. Select File > Import or click Import (near the top left corner of the application) to load the test and environment files.

  3. In the Import dialog, click the Choose Files button, which opens the Open dialog.

  4. Browse to your main solution folder, select the PostManTests.postman_collection.json file, and then click the Open button.

  5. On the Import Elements tab, click Import.

  6. If the COLLECTION EXISTS dialog opens, click Replace.

Having imported the test file, you should see a new collection named Harmony Core Sample API (OData). 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.

  1. Repeat the import process to import the Postman_LocalDevelopment.postman_environment.json file, which is also in the main solution folder. You should then also see a new environment in Postman: LocalDevelopment, which defines a number of environment variables used by the tests in the new collection.

Selecting the Environment

The tests in the Harmony Core Sample API (OData) collection rely on environment variable settings in the LocalDevelopment environment you just imported, so this environment must be set as the active environment for Postman:

  1. Use the Environment selector at the top right of the Postman UI to select LocalDevelopment. (The first time you use Postman, this option will be set to No Environment.)

Configuring Postman to Allow Self-Signed Certificates

The first time you use Postman, you will need to set a Postman option to allow communication with web sites that use self-signed TLS certificates:

  1. Select File > Settings from the Postman menu.

  2. 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.

  3. Close the SETTINGS dialog.

Testing an Endpoint

  1. In Visual Studio, press F5 (Start Debugging) to start the self-hosting application. Once again, you should see the console window appear with a message confirming that your service is running.

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

  3. 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 like this:

Postman Read Customers request

Below the tab for requests, 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}}/{{ODataPath}}/v{{ApiVersion}}/Customers?$top=3

The items in double curly brackets reference environment variables defined in the LocalDevelopment environment. For example, {{ServerBaseUri}} is a reference to an environment variable defined in LocalDevelopment. If you examine the settings in LocalDevelopment, you will see that {{ServerBaseUri}} is set to the base URL of your test service (https://localhost:8086). Defining environment variables in an environment like this makes it easy to change the base URL of the service in one place, thus updating all the requests in the collection.

  1. Click the blue Send button to the right of the URL.

Clicking Send causes Postman to 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:

Harmony Core Logo

You will notice that two tab sets are embedded in the main tab that represents the entire request:

  • 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 contains the JSON data for the top three customers.

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

Status: 200 OK   Time: 17 ms    Size: 1.18 KB

Requests Requiring URL Parameters

When the Postman export file is generated, sample values are inserted for the values of the various keys in some of the URLs. The value 123 is used for the value of numeric fields, and the value ABC is used for the value of alpha fields. You will need to replace these values in the URLs of the various test operations before attempting to execute each test.

  1. Click the Read Customer request.

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}}/{{ODataPath}}/v{{ApiVersion}}/Customers(CustomerNumber=123)
  1. Click the blue Send button.

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

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

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

Stop the Service

  1. When you are done 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

Clone this wiki locally