Views:

Overview

Follow the steps in this article to set up an API Shield Test to check that the Open Exchange Rates API (https://openexchangerates.org/) is working.

Prerequisites

Setup Account on openexchangerates.org:

  • Go to https://openexchangerates.org/ and sign up for an account, using USD as your base currency allows you use a free account
  • Once you have signed up you will get an App ID, copy/note this App ID

To securely store the App ID 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 OpenExchangeRates for the Category
    • Add AppID to the Base Key so that the full BaseKey name is OpenExchangeRates_AppID
    • In the Value Information section enter your Open Exchange Rates App ID 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 Open Exchange Rates 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: Open Exchange Rates 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 Open Exchange Rates API returns the expected number of rates
So that when our systems need to interact with the API I am confident it has not changed
  • Select cell B4, copy and paste https://openexchangerates.org/ (note you must paste [Ctrl+v] directly into cell B4 and not the cell editor at the top of the sheet) 
  • The next steps describe the steps of the test:
    • Select cell B6, for the Given step
      • Enter the text: a valid APP ID
    • Select cell B7, for the When step
      • Enter the text: a GET API request is made to https://openexchangerates.org/api
    • Select cell B8, for the Then step
      • Enter the text: a JSON response with the latest exchange rates is returned
  • Click Save

Arrange

There is no test data to set up for this test as we are calling the API without any input values.

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 Exchange Rates
  • 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://openexchangerates.org/api/'
      • Replace 'resource' with 'latest.json'
      • Replace 'method' with 'GET'
      • Within the SetRequestParams() function, type 'app_id' followed by a comma and a space 
        • Select the Source tab
          • Expand the xCache node
          • Expand the OpenExchangeRates node and click on OpenExchangeRates_AppID,
            •  xCacheGetGlobal('OpenExchangeRates_AppID') will be added to the formula
      • Replace 'responsestatuscode' with 'OK'
      • For SetRequestActionPass replace 'action' with GetVarJsonEC('rates') - for this test we are interested in the rates values
      • For SetRequestActionFail replace 'action' with ThrowError('Exchange Rates 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
      • Click Save

Assert

Once the records have been created we need to check that the calculated values are what we expect. For this test we are introducing a different method to define the Asserts which is based on a existing record - for a lot of tests this will be the fastest way to define your asserts.

  • Select the Assert sheet
  • Select cell B4
    • Select the Functions tab and search for FindEC
    • Select the FindECCount function to add it to cell B4
    • Double click cell B4 or press F2 to enter edit mode
    • Delect the placholder text 'entitycollection' including the quotes, and leave the cursor in its place
    • Select the Source tab
    • Expand the Act node
    • Select Get Exchange Rates (note you may need to click the refresh icon in the top right corner of the Soure tab for this node to show)
  • Select cell C4
    • Enter the number 171 (this is number of rates returned by the API at the time of writing)
  • Select cell D4
    • Enter the text Count Rates 
  • 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 1 pass!), expand this node
    • Expand Step 0001 - Count Rates
      • 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.