AWS Lambda Postman collection runner

An AWS Lambda function to run Postman collections using Newman.

Table of contents

• General info
• Pre-requisites
• Setup
• Invoking the Lambda Postman collection runner
• Viewing Lambda Postman collection runner results

General info

Newman is a command-line collection runner for Postman. This AWS SAM project deploys a single AWS Lambda function that uses Newman to run a Postman collection. By invoking the deployed Lambda function you can run your desired Postman collection to test APIs (and other HTTP endpoints).

The Postman environment payload can be passed as the Lambda invoke event allowing you to run your Postman collection test with your desired Postman environment values. A successful run of the Lambda function will return the Postman test results in JUnit XML format as a base64 encoded field.

Here are some uses for this Lambda:

• Use with Amazon Eventbridge schedule rule to periodically test an API endpoint.
• Use in a CICD pipeline (such as AWS CodePipeline) to test your deployed API endpoint.
• Test an API endpoint in a VPC closed of subnet by deploying the Lambda in to the same VPC.

Be aware of the following considerations when running Postman collection tests from Lambda:

• Lambda has a maximum run time of 15 minutes. You should make sure your Postman collection tests do not take longer than this.
• By default, Lambda is deployed with internet connectivity but without connectivity to any of your VPC resources. You need to configure your Lambda networking so that it can reach where you API endpoint to test is located.

Pre-requisites

• Node.js - Install Node.js 18, including the npm package management tool.
• AWS SAM CLI - Install the AWS SAM CLI.
• AWS CLI - Install the AWS CLI

Setup

Place your exported Postman collection files in the collections directory.

To build and deploy your application for the first time, run the following in your shell:

sam build
sam deploy --guided

When prompted for the Parameter postmanCollection, enter the name of Postman collection file that you want to run (that you had placed in the collections directory):

Parameter postmanCollection [default.postman_collection.json]: sample.postman_collection.json

Take note of the Lambda Function name in the output lambdaFunctionName. Example output:

-----------------------------------------------------------------------------------
Outputs                                                                                                                                                                                                                                                                                                              
-----------------------------------------------------------------------------------
Key                 lambdaFunctionName                                                                                                                                                                                                                                                                               
Description         Lambda Function name                                                                                                                                                                                                                                                                             
Value               aws-lambda-postman-collec-lambdaFunctionPostmanCol-xxxxxxxxxxxx                                                                                                                                                                                                                                  
-----------------------------------------------------------------------------------

Invoking the Lambda Postman collection runner

Obtain your deployed Lambda Function name from the sam deploy output lambdaFunctionName. Alternatively, you can retrieve the function name from the CloudFormation stack output using the following command:

Replace ${STACK_NAME} with your SAM deployed CloudFormation stack name.

aws cloudformation describe-stacks --stack-name ${STACK_NAME}

To invoke Lambda Postman collection runner without any Postman environment variables use the following command:

Replace ${FUNCTION_NAME} with your SAM deployed Lambda Function name.

aws lambda invoke --function-name ${FUNCTION_NAME} invoke-response.json

To invoke Lambda Postman collection runner with Postman environment variables, first prepare the Postman environment variables file. This can be exported from Postman (providing a *.postman_environment.json file). Then use the following command that references the file:

Replace ${ENVIRONMENT_FILE} with your Postman environment variable file.

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

The Lambda invocation output is written to the file invoke-response.json.

Viewing Lambda Postman collection runner results

The Postman collection run results is contained in the Lambda invocation output that is written to the file invoke-response.json.

Example invoke-response.json:

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

The Postman collection run XML Junit output is base64 encoded in the encoded field. You can using the following command with jq to decode it straight from the invoke-response.json file.

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

The Newman output containing the Postman collection run information is written to the Lambda's CloudWatch logs. The CloudWatch Log group path is /aws/lambda/<LAMBDA_FUNCTION_NAME>.

Example Lambda CloudWatch logs:

INIT_START Runtime Version: nodejs:18.v5	Runtime Version ARN: arn:aws:lambda:ap-southeast-2::runtime:c869d752e4ae21a3945cfcb3c1ff2beb1f160d7bcec3b0a8ef7caceae73c055f
START RequestId: 37f0f752-c2ae-4b30-9ac4-8ad0a03122f4 Version: $LATEST
2023-04-03T00:10:34.603Z	37f0f752-c2ae-4b30-9ac4-8ad0a03122f4	INFO	Begining API Tests with Postman collection /var/task/collections/sample.postman_collection.json
2023-04-03T00:10:34.603Z	37f0f752-c2ae-4b30-9ac4-8ad0a03122f4	INFO	Output path: /tmp/apitestsuites_xmlresults.xml
newman
sample
→ Mock request
GET https://postman-echo.com/get?foo1=bar1&foo2=bar2 
[200 OK, 821B, 1420ms]
✓  response is ok
✓  response body has json with request queries
→ Mock request using env vars
GET https://postman-echo.com/get?foo1=foo&foo2=bar [200 OK, 929B, 226ms]
✓  response is ok
✓  response body has json with request queries
┌─────────────────────────┬─────────────────────┬─────────────────────┐
│                         │            executed │              failed │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│              iterations │                   1 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│                requests │                   2 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│            test-scripts │                   4 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│      prerequest-scripts │                   2 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│              assertions │                   4 │                   0 │
├─────────────────────────┴─────────────────────┴─────────────────────┤
│ total run duration: 2.8s                                            │
├─────────────────────────────────────────────────────────────────────┤
│ total data received: 1.12kB (approx)                                │
├─────────────────────────────────────────────────────────────────────┤
│ average response time: 823ms [min: 226ms, max: 1420ms, s.d.: 597ms] │
└─────────────────────────────────────────────────────────────────────┘