Introduction

In this two-part blog post, I'm going to show you how you can run a Postman collection in an AWS Lambda function to test your APIs. Postman is a tool that can be used to test APIs. These Postman tests can be exported into a Postman collection file and run in an AWS Lambda function using Newman.

With this Lambda function, you can run your API tests in Postman with a single Lambda function invocation call. By taking advantage of this, you can achieve automated API testing in a serverless way. For example, you could configure a release pipeline to trigger the Lambda function to test an API after your API has been deployed.

For this Part 1 post, I will cover how to set up scheduled tests of the publicly available API, OpenWeather using Postman, AWS Lambda and Amazon EventBridge Scheduler.

In Part 2, I will cover how to set up a similar Postman and AWS Lambda combination, to test a private API within an AWS VPC private subnet.

Pre-requisites

This demonstration uses the following applications:

AWS Account access
Postman - Install Postman
Node.js - Install Node.js 18
AWS SAM CLI - Install the AWS SAM CLI
AWS CLI - Install the AWS CLI

Create a Postman collection to test your API

I will be using OpenWeather API to create a Postman collection for API testing. This is a public API that is free to use after signing up. You can follow along with this API or choose a different API to create a Postman collection for API testing, in which case you will need to write your own tests in Postman.

You can sign up for OpenWeather Free plan to receive an API key. Note that the API key may take a few hours to become active.

Create a new collection in Postman (for OpenWeather API)

In Postman, under Collections, click the '+' icon to create a collection. Click the pencil icon to rename the collection to "OpenWeather":

Select your new "OpenWeather" collection and click the Variables tab. Add the following variables:

api_key - Your OpenWeather API key
location - Location to check the weather in the format {city name},{country code}. Some example locations: Auckland,NZ, Sydney,AU, London,UK
desired_temp - Choose any desired temperature in Degrees Celsius (e.g. 18).

Click the Authorization tab. Under Type select API Key. Configure the following Authorization values:

Key - appid
Value - {{api_key}}
Add to - Query Params

On the top right corner, click Save.

Add a request to the collection

Click the drop-down arrow next to the collection and click Add a request.

Name the request "Weather".

In the URL field paste the following URL:

https://api.openweathermap.org/data/2.5/weather?units=metric&q={{location}}

On the top right corner, click Save.

Click Send to send the request. You should receive a 200 response, with a JSON body containing weather information.

Add tests to your request

We will add the following test to our OpenWeather API GET Weather request:

Expect the response status code to be 200.
Expect the response body JSON main.temp is greater than or equal to the set Postman collection variable desired_temp.

Under your selected "GET Weather" request, click the Tests tab.

Paste the following test code then click Save:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});
let desired_temp = Number(pm.variables.get("desired_temp"));
pm.test("Above desired temperature", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData.main.temp).to.be.gte(desired_temp);
});

Click Send to send another request and run the tests.

Depending on your Collection variable values for location and desired_temp, the "Above desired temperature" may pass or fail.

If you would like to know more about writing tests in Postman, see Postman's official site documentation: https://learning.postman.com/docs/writing-scripts/test-scripts/

Export your Postman collection file

To export your Postman collection to a JSON file, next to your Collection name, click the 3 horizontal dots (more options) icon, then click Export.

Choose a location to temporarily store the Postman collection JSON file (OpenWeather.postman_collection.json).

Deploy AWS Lambda Postman collection runner

The Lambda function that we will use to carry out API testing uses Node.js and Newman to run a Postman collection file. This Lambda function is deployed using AWS SAM. You can find the source code for this Lambda at: https://github.com/FreddyCLH/aws-lambda-postman-collection-runner

Use AWS SAM to deploy the Lambda

Clone the AWS Lambda Postman collection runner project:

git clone https://github.com/FreddyCLH/aws-lambda-postman-collection-runner.git

Copy the OpenWeather Postman collection file to the collections folder:

cd aws-lambda-postman-collection-runner/
# Example copy of the Postman collection file on the Desktop
cp ~/Desktop/OpenWeather.postman_collection.json collections

Build and deploy the SAM project:

sam build
sam deploy --guided

When prompted with "Parameter postmanCollection", enter "OpenWeather.postman_collection.json":

When prompted to "Deploy this Changeset?", enter "y".

Take note of the output lambdaFunctionName. This will be used later when invoking the specified Lambda function name.

Invoke the Lambda function to test the API

Create the file api_test_params.json with the following contents below. This contains the Postman variables values to be used as the Lambda input payload. Feel free to change the values for location and desired_temp to what you want:

{
    "values": [
        {
            "key": "location",
            "value": "Auckland,NZ",
            "type": "default",
            "enabled": true
        },
        {
            "key": "desired_temp",
            "value": "18",
            "type": "default",
            "enabled": true
        }
    ]
}

Invoke the function with the following command, replacing ${FUNCTION_NAME} with your Lambda function name (obtained from the CloudFormation output lambdaFunctionName):

aws lambda invoke --function-name ${FUNCTION_NAME} \
  --payload file://api_test_params.json \
  invoke-response.json \
  --cli-binary-format raw-in-base64-out

Example Lambda function invoke command and response:

$ aws lambda invoke --function-name aws-lambda-postman-collec-lambdaFunctionPostmanCol-CXcPZPsxlfuY \
$  --payload file://api_test_params.json \
$  invoke-response.json \
$  --cli-binary-format raw-in-base64-out
{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

Inspect the Lambda functions response in the invoke-response.json file. You should see StatusCode: 200 as well as the metrics about your run Postman collection.

{
  "StatusCode": 200,
  "message": "Run completed successfully!",
  "encoded": "....",
  "stats": {
    ...omitted for brevity...
    "assertions": {
      "total": 2,
      "pending": 0,
      "failed": 0
    },
    "testScripts": {
      "total": 2,
      "pending": 0,
      "failed": 0
    }
  }
}

The encoded field contains the base64 encoded XML Junit output. You can use the following command with jq installed to view it:

jq -r '.encoded' invoke-response.json | base64 --decode

Example XML Junit output:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="OpenWeather" tests="1" time="0.435">
  <testsuite name="Weather" id="3159adda-ae6d-4aab-90c9-8d705e50d075" timestamp="2023-04-23T01:50:15.911Z" tests="2" failures="0" errors="0" time="0.435">
    <testcase name="Status code is 200" time="0.435" classname="OpenWeather"/>
    <testcase name="Above desired temperature" time="0.435" classname="OpenWeather"/>
  </testsuite>
</testsuites>%

The Newman Postman collection run output is written to the Lambda function's logs in CloudWatch Logs (https://console.aws.amazon.com/logs).

In the AWS Console, under CloudWatch Log groups, navigate to the Lambda functions log group with the name pattern: "/aws/lambda/${FUNCTION_NAME}".

Example CloudWatch logs showing the GET request and run tests:

Schedule the Lambda with Amazon EventBridge Scheduler

Amazon EventBridge Scheduler can be used to define a cron schedule to invoke the Postman collection runner Lambda function. By doing so, we can periodically run our API tests.

Create an EventBridge Schedule to invoke the Lambda

In the AWS Console, navigate to the Amazon EventBridge Scheduler at https://console.aws.amazon.com/scheduler/home.

Click Create schedule.

In Step 1 - Specify schedule detail, enter a Schedule name. For example "api-test-openweather-auckland-nz".

Leave Schedule group with "default".

Under Schedule pattern, select Recurring schedule and Cron-based schedule.

Configure your desired cron schedule then click Next. The below image shows a cron schedule that runs every minute.

In Step 2 - Select Target, under Target detail, select Frequently used APIs and AWS Lambda.

Under Invoke AWS Lambda, enter or locate your Lambda function name.

In the Input field, enter the same content as what you had entered in the api_test_params.json file (see Invoke the Lambda function to test the API).

Click Skip to Review and create schedule then Create schedule.

To check that your schedule is now running and invoking the Lambda, view the Lambda's logs in CloudWatch logs (console.aws.amazon.com/logs).

In the AWS Console, under CloudWatch Log groups, navigate to the Lambda functions log group with the name pattern: "/aws/lambda/${FUNCTION_NAME}".

You should see timestamped entries that correspond to your defined EventBridge schedule.

The below image shows a search of the string "GET api.openweathermap.org" across all the Lambda functions log stream. You can see that there is an entry every minute, corresponding to our configured EventBridge cron-based schedule.

Conclusion

In this post, we used an AWS Lambda function using the Node.js package Newman to run a Postman collection. In the Postman collection, we had written tests for the public OpenWeather API as an example. You can use Postman to write tests for any API, then export the Postman collection file to be included and run in the Postman collection runner Lambda function.

An Amazon EventBridge schedule was created to invoke the Lambda function. By doing so, we can periodically run our API tests. The Postman collection run output is written to the Lambda function's CloudWatch Logs.

API tests can now be triggered with a Lambda function invocation call. You can take advantage of this in creative ways to automate your API testing. For example, you could configure a release pipeline to trigger the Lambda function to test an API after your API has been deployed.

In Part 2, we will look at using the Postman collection runner Lambda function to test APIs located inside AWS VPC private subnet with restrictive inbound network access. In addition, we will use CloudWatch metric filters to show our API testing results in a graph.

Freddy's AWS 2 cents