Create an API Shield Test to check OpenWeather API returns 5 days forecast for specific cities

Views:

Overview

For some businesses weather information can be crucial to operations. This information is often obtained by a 3rd party provider via an API and systems will expect the API is operating and consistent. Follow the steps in this article to set up an API Shield Test to check that the OpenWeather API (https://openweathermap.org/) is returning 5-day forecast data (40 3-hour forecasts) for a specific list of cities.

Prerequisites

Setup free Account on openweathermap.org:

Go to https://openweathermap.org/appid and sign up for a free account
Once you have signed up you will be provided with an API Key (found on the API Keys tab), copy/note this API Key

To securely store the API Key we use an xCache record. Only System Administrators or specifically authorized users will be able to access this value.

Open the North52 Decision Suite app
Navigate to Business Process Activities > xCache
Create a new xCache record
- Enter OpenWeatherMap for the Category
- Add APIKey to the Base Key so that the full BaseKey name is OpenWeatherMap_APIKey
- In the Value Information section enter your API Key into the Value (Secured) field
Click Save

Create the Test

Initial Set up

Open the North52 Decision Suite app
Navigate to TestShield > Tests
Click New
On the Register tab
- For Test Plan enter Training
- For Test Suite enter API Test
- For Test Case enter OpenWeatherMap API
- For Test Type select API Shield
- For Sync or Async select Sync
Click Save

Assemble

On the Assemble sheet we describe the specific scenario of a feature that will be tested and outline the steps of the test using Gherkin-style syntax.

On the Assemble sheet, edit cell B1 to describe the Feature being tested. Enter the text: OpenWeatherMap API

Double-click cell B2

For the Scenario, describe what is being tested - we like to use a User Story. Enter the text:

As an Administrator
I want to ensure the the OpenWeatherMap API returns the expected number of forecasts for the cities provided
So that when our systems need to interact with the API I am confident it is working correctly

Select cell B4, copy and paste https://openweathermap.org/
The next steps describe the steps of the test:
- Select cell B6, for the Given step
  - Enter the text: a valid API Key
- Select cell A7, right click and select Insert > Insert Row
  - In cell A7, enter the text And
- Select cell B7, for the And step
  - Enter the text: a list of cities
- Select cell B8, for the When step
  - Enter the text: a GET API request is made to api.openweathermap.org with the city defined
- Select cell B9, for the Then step
  - Enter the text: a JSON response with the 5 day forecast is returned
Click Save

Arrange

We need to create a list of cities that we want to check so define these on the Arrange sheet. For the purposes of this exercise we are going to check New York, Los Angeles and London.

Select the Arrange sheet
Select cell A2
- Replace the existing placholder text with: City
Select cell B2
- Replace the existing placeholder text with: Country Code

Note: if we needed further parameters defined, we can add additional data columns by right-clicking and selecting Insert > Insert Action

Select cell A4, enter 'New York'
Select cell B4, enter 'us'
Select cell A5, enter 'Los Angeles'
Select cell B5, enter 'us'
Select cell A6, enter 'London'
Select cell B6, enter 'uk'

Act

The Act Sheet allows you to execute any functions after the Arrange sheet(s) have been processed. For this test we need to call the API using the North52 CallRestAPI function.

Select the Act sheet
Select cell A4
- Enter the text Get New York Forecast
Select cell B4
- Expand the editor for the cell by clicking the + in the top right of the sheet
- Select the Functions tab and type callrest into the Search functions input box and press enter
- Click on the CallRestAPI function to add it to the formula editor
  - Replace 'baseurl' with 'https://api.openweathermap.org/'
  - Replace 'resource' with 'data/2.5/forecast'
  - Replace 'method' with 'GET'
  - Within the SetRequestParams() function, type 'q' followed by a comma and a space
    - Select the Source tab
      - Expand the Arrange node
        
        Expand the Arrange-Row-0004
        
        Select Arrange-Row-0004-City
        
        GetVarTestData('Arrange-Row-0004-City') will be added to the formula
    - Immediately after this type + ',' + with a space either side
    - From under the Arrange-Row-0004 node, select Arrange-Row-0004-Country Code
      - GetVarTestData('Arrange-Row-0004-Country Code') will be added to the formula
    - Immediately after this type , 'APPID', including the commas
    - Expand the xCache node
    - Expand the OpenWeatherMap node and click on OpenWeatherMap_APIKey,
      - xCacheGetGlobal('OpenWeatherMap_APIKey') will be added to the formula
  - Replace 'responsestatuscode' with 'OK'
  - For SetRequestActionPass replace 'action' with GetVarJsonValue('cnt') - cnt is the count of forecast items that are returned and for this test we are interested how this value compares to the 40 we expect
  - For SetRequestActionFail replace 'action' with ThrowError('Weather Request Failed: ' + GetVar('responsecontent')) - this will present a standard Business Process error message with any details supplied by the API if there is an error
  - The CallRestAPI function should look like this:
  - Click the X button in the top right of Decision Table sheet to close the formula editor
We need to use the same method to call the API for the other parameters defined on our Arrange sheet, but we can do it very quickly
- Select cell A5
  - Enter the text Get Los Angeles Forecast
- Select cell A6
  - Enter the text Get London Forecast
- Select cell B4, and position the cursor over the bottom right corner of the cell to show the fill handle
  - Drag down 2 rows to cell B6, this will copy the formula into these cells
- Select cell B5, and expand the editor for the cell by clicking the + in the top right of the sheet
  - Replace the two Arrange-Row references 0004 with 0005, or you could delete them and click on the relevant nodes in the Source tab, however directly editing them is much quicker
  - Click the X button in the top right of Decision Table sheet to close the formula editor
- Select cell B6, and expand the editor for the cell by clicking the + in the top right of the sheet
  - Replace the two Arrange-Row references 0004 with 0006
  - Click the X button in the top right of Decision Table sheet to close the formula editor
Click Save

Assert

Once the API has been called for each row in the Act sheet we need to check that the returned values are what we expect.

Select the Assert sheet
Select cell A4, leaving the default Assert Type as AssertAreEqual
Select cell B4
- Select the Source tab
- Expand Act
  - Select Get New York Forecast
Select cell C4
- Enter the number 40
Select cell D4
- Enter the text Count New York
Select cell B5
- Select the Source tab
- Expand Act
  - Select Get Los Angeles Forecast
Select cell C5
- Enter the number 40
Select cell D5
- Enter the text Count Los Angeles
Select cell B6
- Select the Source tab
- Expand Act
  - Select Get London Forecast
Select cell C6
- Enter the number 40
Select cell D6
- Enter the text Count London
Your Arrange sheet should now look like:

Click Save

Run the Test

The Test is now ready to be run. For this exercise we will run the Test manually.

Click the Execute Test button - represented by the lightning button in the top right of the Test editor canvas
Click the Execute button on the fly-out pane
After a few seconds the Test result record will be created (a message Result: Operation Completed will be shown)
From the Source tab, expand Test Run Results
- You will see a node with with the time of your test and the Pass/Fail results (you should have 3 passes!), expand this node
- Expand Step 0001 - Count New York
  - You will see the Actual and Expected values

If the API has changed since the time of writing the test you will know as there will be a failure, which could easily be a real life scenario when you are relying on 3rd party APIs.