API Gateway Template Tester

Provides useful AWS API Gateway templating methods for rendering API Gateway Apache Velocity Templates locally.

Particularly useful for integrating into your testing suite for an API Gateway implementation.

The purpose of this tiny library, is to enable testing of velocity templates in a standalone environment, to ensure that they render requests and responses correctly, when deployed inside API Gateway.

Getting Started

Given an Apache Velocity template like the one below:

{
  "hello": "$input.params('name')"
}

const api = require('api-gateway-template-tester');
 
const template = fs.readFileSync('./velocity-template.vm', { encoding: 'utf8' });
 
const test = api().queryStrings({ name: 'David' });
 
test.render(template);

The following string content would be rendered:

{
  "hello": "David"
}

Each function call return an immutable API object, allowing you to chain methods together, in-order to build up your API in test suites, applying different templates, or request contexts easily.

An example of how to integrate this library into your existing test suite can be found here.

Supported Methods

$context

Context keys are not setup by default, see the documentation below.

Method	Supported
$context.apiId	✅
$context.authorizer.claims.property	✅
$context.authorizer.principalId	✅
$context.authorizer.property	✅
$context.httpMethod	✅
$context.error.message	❌
$context.error.responseType	❌
$context.identity.accountId	✅
$context.identity.apiKey	❌
$context.identity.caller	❌
$context.identity.cognitoAuthenticationProvider	❌
$context.identity.cognitoAuthenticationType	❌
$context.identity.cognitoIdentityId	✅
$context.identity.cognitoIdentityPoolId	✅
$context.identity.sourceIp	✅
$context.identity.user	❌
$context.identity.userAgent	✅
$context.identity.userArn	❌
$context.requestId	✅
$context.resourceId	✅
$context.resourcePath	✅
$context.stage	✅

$input

Method	Supported
$input.body	✅
$input.json(x)	✅
$input.params()	✅
$input.params(x)	✅
$input.path(x)	✅

$stageVariables

Method	Supported
$stageVariables	✅

$util

Method	Supported
$util.escapeJavaScript()	✅
$util.parseJson()	✅
$util.urlEncode()	✅
$util.urlDecode()	✅
$util.base64Encode()	✅
$util.base64Decode()	✅

API

Note that api() objects are immutable which means every additional call added will return a new object.

.body(Object | String)

Defines the HTTP body of the request or response that the template will be rendered with. This body can either be a JS Object or a string.

Note if an object is used, it is stringified (JSON.stringify()).

const fs = require('fs');
 
const request = fs.readFileSync('./my-request.json', { encoding: 'utf8' });
 
const test = api().body(request);

.pathParameters(Object)

Sets any expected parameters that may exist in the path. For example, if you have an API Gateway path such as /books/{id}, you could set this like:

const test = api().pathParameters({ id: 1 });

.headers(Object)

Sets any custom headers that are to be expected in the request. Basic HTTP Headers are not currently set automatically (like Content-Type) and adding authorization headers like Authorization or X-Api-Key, header will not populate the $context key.

const name = 'X-Custom-Header';
 
const value = '1234567890'
 
const test = api().headers({ [name]: value });

.queryStrings(Object)

Sets any expected query string parameters. Given a path which expects the query parameter ?book= you may define this using:

const test = api().queryStrings({ book: 9 });

.stageVariables(Object)

Sets any stage variables that are present on the API Gateway deployment.

const variables = { IAMExecutionRoleName: 'api-gateway-execution-role-1j39gja' };
 
const test = api().stageVariables(variables);

.context(Object)

Update the $context key for used to render the template.

const cognitoIdentityPoolId = 'us-east-1_j99jXio39f';
 
const test = api().context({ identity: { cognitoIdentityPoolId } });

.render(String)

A terminal method that renders the template passed in as an argument, using the built up immutable object.

const api = require('api-gateway-template-tester');
 
const template = fs.readFileSync('./velocity-template.vm', { encoding: 'utf8' });
 
const request = fs.readFileSync('./example-request.json', { encoding: 'utf8' });
 
const test = api();
 
const variables = { IAMExecutionRoleName: 'api-gateway-execution-role-1j39gja' };
 
const setup = api().stageVariables(variables).context({ apiId: '2ja29tjJJ9jd' });
 
const test = setup().body(request)
                    .pathParameters({ id: 1 })
                    .headers({ 'X-Custom-Header': '1234567890' })
                    .queryStrings({ book: 9 });
 
test.render(template);

Populating Context

By default, the $context key is an empty object and context for the request is not generated.

If you're request uses the $context key, you can setup defaults, as well as add faker authorization data using the methods below:

const api = require('api-gateway-template-tester');
const context = require('api-gateway-template-tester/context');
 
// calling this provides some basic defaults such as $context.apiId
const test = api().context(context.defaults());

In addition to adding randomly generated context data, we can add Cognito User Pool authorization data, as demonstrated below:

const authorization = context.cognitoUserPoolAuthorization();
 
const test = api().context(context.defaults()).context(authorization);

This uses the faker library to generate realistic authorization data and adds it to the $context key. This method populates keys such as $context.authorizer.claims.username.