node package manager


Build Status npm version


Simplifies writing unit tests for AWS Lambda functions using Node.js.


  • Verifies correct handler behavior
  • Works asynchronously
  • Verifies Node.js runtime version
  • AWS X-Ray support [experimental]
  • Detects resource leaks [experimental]
  • Supports Promises
  • Easily integrates with test frameworks (Mocha and Jasmine)
  • Handlers can be loaded and removed after execution
  • Lightweight and won't impact performance
  • Maps the environment variable LAMBDA_TASK_ROOT to the application's root
  • Automatically loads .env files
  • Works with Node 6.10.x


Install via npm.

npm install lambda-tester --save-dev

Getting Started

Lambda handlers with support for callbacks use the typical Node.js asynchronous signature:

exports.handler = function( event, context, callback ) {
    callback( null, 'success!' );

The following example shows a simple case for validating that the Lambda (handler) was called successfully (i.e. callback( null, result ):

const LambdaTester = require( 'lambda-tester' );
const myHandler = require( '../index' ).handler;
describe( 'handler', function() {
    it( 'test success', function() {
        return LambdaTester( myHandler )
            .event( { name: 'Fred' } )

If the handler decides to call callback( err ) then the verification will fail and the test will fail.

Additionally, if one wanted to test for failure, then the following code would be used:

const LambdaTester = require( 'lambda-tester' );
const myHandler = require( '../index' ).handler;
describe( 'handler', function() {
    it( 'test failure', function() {
        return LambdaTester( myHandler )
            .event( { name: 'Unknown' } )

Please note that you must return the LambdaTester back to the framework since lambda-tester is asynchronous and uses Promises.


Complete documentation can be found in our documentation page.

Projects Using lambda-tester

  • vandium - Secures and simplifies AWS Lambda handlers


We'd love to get feedback on how you're using lambda-tester and things we could add to make this tool better. Feel free to contact us at


Version 3.x targets Lambda handlers using Node 6.10.x. If you require support for Node 4.x, please use version 2.x