Registry / aws / aws-lambda-test-utils

aws-lambda-test-utils

JSON →
library1.3.0jsnpmunverified

aws-lambda-test-utils is a JavaScript utility library designed to simplify the local testing of AWS Lambda functions. It provides helper functions to mock the `context` object and various AWS service `event` objects (e.g., S3, SNS, DynamoDB, API Gateway) that a Lambda function typically receives. This allows developers to run their Lambda logic outside of the AWS environment for faster, automated testing. The current stable version is 1.3.0. As of the provided information, it primarily supports CommonJS imports, and its release cadence appears to be infrequent, given the version number and the project's age (last commit several years ago). Its key differentiator is its focus on providing simple, predefined mocks for common AWS event types, reducing the boilerplate needed for basic Lambda unit tests, particularly for projects still relying on older callback-style Lambda handlers.

awstesting
npm install aws-lambda-test-utils
github ↗package ↗
INSTALL
IMPORT
SIG · AWS-LAMBDA-TEST-UT
A
aws-lambda-test-utils
awsjavascriptv1.3.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mockContextCreator
✓ const { mockContextCreator } = require('aws-lambda-test-utils');
✗ import { mockContextCreator } from 'aws-lambda-test-utils';
This package is a CommonJS module. Direct ESM 'import' will fail unless transpiled or using a CJS wrapper.
mockEventCreator
✓ const { mockEventCreator } = require('aws-lambda-test-utils');
✗ import { mockEventCreator } from 'aws-lambda-test-utils';
Provides methods like `createDynamoDBEvent`, `createSNSEvent`, `createS3Event`, and `createAPIGatewayEvent`.
utils
✓ const utils = require('aws-lambda-test-utils');
✗ import * as utils from 'aws-lambda-test-utils';
The default export for the entire utility collection, containing both `mockContextCreator` and `mockEventCreator`.

Demonstrates how to use `mockContextCreator` to simulate an AWS Lambda execution context with both default and custom options, enabling local testing of a callback-style Lambda handler with a specific event payload. This setup is typical for unit testing Lambda functions outside of the AWS environment.

const test = require('tape'); // A testing framework like 'tape' is recommended const { mockContextCreator } = require('aws-lambda-test-utils'); // Simulate your Lambda handler function const myLambdaHandler = { handler: (event, context) => { setTimeout(() => { if (event && event.key1) { // Simulate success for callback-style Lambda context.succeed(event.key1); } else { // Simulate failure context.fail(new Error("Missing 'key1' in event.")); } }, 10); } }; const testEvent = { key1: 'expectedValue' }; const contextOptions = { functionName: 'TestLambdaFunction', functionVersion: '$LATEST', invokedFunctionArn: 'arn:aws:lambda:us-east-1:123456789012:function:TestLambdaFunction' }; test('Lambda Handler Test Suite', function(t) { t.test("Handler returns correct value for 'key1' using simple context", function(st) { function callback(error, result) { st.error(error, "No error expected"); st.equals(result, testEvent.key1, "Result should match event.key1"); st.end(); }; const context = mockContextCreator({}, callback); myLambdaHandler.handler(testEvent, context); }); t.test("Handler returns correct value for 'key1' using custom context options", function(st) { function callback(error, result) { st.error(error, "No error expected"); st.equals(result, testEvent.key1, "Result should match event.key1"); st.end(); }; const context = mockContextCreator(contextOptions, callback); myLambdaHandler.handler(testEvent, context); }); t.end(); });
Debug
Known issues
gotchaThe package is primarily designed for CommonJS (CJS) environments, as indicated by its `require()` syntax usage in documentation. Attempting to use ESM `import` syntax directly will likely result in module resolution errors without proper transpilation or a CJS wrapper.
fix
Use CommonJS `require()` syntax: `const { symbol } = require('aws-lambda-test-utils');` or configure your build system (e.g., Webpack, Rollup) to correctly transpile CJS modules for ESM usage.
affects: all
gotchaThe project repository has not been updated in over 4 years. While the package may remain functional for older Lambda runtimes and event structures, it may not reflect the latest AWS Lambda features, new event types, or modern Node.js runtime best practices. This could lead to incomplete or inaccurate mocks for newer AWS services or Lambda patterns.
fix
Review the package's source code and current AWS Lambda documentation to ensure compatibility with your specific use case. For new projects or those using modern AWS features, consider more actively maintained alternatives or be prepared to extend/fork this package.
affects: all
gotchaThe `mockContextCreator`'s callback-based success/failure (`context.succeed`, `context.fail`) reflects an older Lambda handler pattern. Modern Lambda handlers commonly use `async/await` or return Promises. This package's mocks might not fully emulate the behavior of Promise-based handlers without manual adaptation in your test setup.
fix
When testing `async/await` Lambda handlers, ensure your test setup correctly awaits the handler's returned promise and maps its resolution/rejection to your test expectations, potentially wrapping the `mockContextCreator` callback to resolve a promise.
affects: all
Errors
Common errors & fixes
Error: Cannot use import statement outside a module
Attempting to use ESM 'import' syntax for `aws-lambda-test-utils` in a CommonJS-only project or a file not configured as an ESM module.
fix
Change your import statement to use CommonJS `require()`: `const { mockContextCreator } = require('aws-lambda-test-utils');`
TypeError: context.succeed is not a function
The mock context's callback handler (`context.succeed`, `context.fail`) is not being invoked correctly within your Lambda handler, or your test is not providing a function to handle these calls.
fix
Ensure the `mockContextCreator` is provided with a valid callback function as its second argument (`mockContextCreator(options, callback)`). Verify that your Lambda handler correctly calls `context.succeed()` or `context.fail()` when using the callback pattern.
Upgrade
Version history
1.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
2
Resources
githubhttps://github.com/dwyl/aws-lambda-test-utils ↗
packagehttps://www.npmjs.com/package/aws-lambda-test-utils ↗
aws-lambda-test-utils — npm install aws-lambda-test-utils · libregistry