AWS SDK Mocking Library for JavaScript v2

6.2.2 · maintenance · verified Sun Apr 19

aws-sdk-mock is a JavaScript/TypeScript library designed to facilitate unit testing of applications that interact with the AWS SDK, specifically targeting AWS SDK for JavaScript v2. It enables developers to replace actual AWS service calls with predefined responses or custom functions during tests, preventing unintended interactions with real AWS infrastructure. The current stable version is 6.2.2. While there isn't a strict time-based release cadence, the project is actively maintained, with recent minor updates addressing dependencies and security vulnerabilities (e.g., v6.2.0 addressing CVE-2024-45296) and a significant TypeScript rewrite in v6.0.1. It differentiates itself by leveraging Sinon.js internally to create robust mocks for AWS service methods like S3.getObject or DynamoDB.putItem, offering explicit `mock`, `restore`, and `remock` functions. A key limitation and differentiator is its primary focus on AWS SDK v2; for AWS SDK v3, direct mocking of modular clients might be preferred, reducing the need for this library.

Common errors

```
Error: Cannot find module 'aws-sdk'
```
cause The 'aws-sdk' package is not installed in your project, or is not resolvable by Node.js.

fix Install the AWS SDK v2: `npm install aws-sdk@2` or `yarn add aws-sdk@2`.
```
TypeError: (0, aws_sdk_mock_1.mock) is not a function
```
cause You are attempting to import the `mock` function incorrectly, likely as a default import when it is a named export.

fix Use a named import: `import { mock, restore } from 'aws-sdk-mock';`
```
TypeError: Cannot read properties of undefined (reading 'putObject') (or similar for other AWS services/methods)
```
cause This error often occurs when trying to mock an AWS service or method that either doesn't exist on the `aws-sdk` object, or the `aws-sdk` client itself hasn't been properly configured/initialized in a way that `aws-sdk-mock` can intercept it. This is common when attempting to use it with AWS SDK v3 clients.

fix Ensure you are using AWS SDK v2. Verify the service name (e.g., 'S3', 'DynamoDB') and method name (e.g., 'putObject', 'getItem') are correct and match the v2 API. Confirm that `aws-sdk` is imported and used in the code you are testing.

Warnings

breaking aws-sdk-mock is primarily designed for AWS SDK for JavaScript v2. It is NOT recommended for use with AWS SDK v3 (modular SDK). For v3, consider direct mocking techniques or purpose-built v3 mocking libraries.
Fix: If using AWS SDK v3, refactor your tests to use standard mocking patterns directly on the modular v3 clients or explore v3-specific mocking solutions. Do not attempt to use aws-sdk-mock with v3 clients.
breaking Version 6.0.1 included a complete TypeScript rewrite of the library. While the core API remained largely similar for JavaScript users, this introduced changes to type definitions and internal structure, potentially impacting existing TypeScript projects.
Fix: Review type declarations in your project if upgrading from pre-v6 to ensure compatibility. Re-check any custom type assertions or extensions related to aws-sdk-mock.
gotcha A minor maintenance release (v6.2.0) updated dependencies to address a security vulnerability (CVE-2024-45296) in one of its transitive dependencies.
Fix: Upgrade to aws-sdk-mock v6.2.0 or later to ensure you have the security fix.
gotcha The README examples often show `AWS.mock(...)` for usage, which can be misleading. The library exports `mock`, `restore`, and `remock` as named exports.
Fix: Always use named imports: `import { mock, restore, remock } from 'aws-sdk-mock';` or CommonJS `const { mock, restore, remock } = require('aws-sdk-mock');`

Install

npm install aws-sdk-mock npm
yarn add aws-sdk-mock yarn
pnpm add aws-sdk-mock pnpm

Imports

mock
wrong:
```
import AWSMock from 'aws-sdk-mock';
AWSMock.mock(...);
```
correct:
```
import { mock } from 'aws-sdk-mock';
```
The library primarily uses named exports. The README's 'AWS.mock(...)' notation is a common pattern but not a direct import style for the functions themselves.

restore

wrong:

const { restore } = require('aws-sdk-mock'); // For CommonJS
// Or incorrect usage like AWSMock.restore(...);

correct:

import { restore } from 'aws-sdk-mock';

Used to revert mocked AWS service methods to their original implementations. It's crucial for cleaning up tests.

remock
wrong:
```
import AWS from 'aws-sdk-mock';
AWS.remock(...);
```
correct:
```
import { remock } from 'aws-sdk-mock';
```
Allows updating the replacement function for an already existing mock without needing to restore and re-mock, useful in multi-step tests.

Quickstart

Demonstrates how to mock an AWS SDK v2 S3 client's `getObject` method, execute a call, and then restore the original method.

import { S3 } from 'aws-sdk';
import { mock, restore } from 'aws-sdk-mock';

// Ensure aws-sdk@2 is installed (e.g., `npm i aws-sdk@2`)
// This example uses an async IIFE for demonstration.

(async () => {
  const bucket = 'my-mock-bucket';
  const key = 'test-file.txt';
  const mockData = { Body: Buffer.from('Mocked content!') };

  // 1. Mock an S3 service method
  mock('S3', 'getObject', (params, callback) => {
    console.log(`Mocking S3.getObject for ${params.Bucket}/${params.Key}`);
    callback(null, mockData);
  });

  // 2. Use the AWS SDK client as usual
  const s3Client = new S3();
  const result = await s3Client.getObject({ Bucket: bucket, Key: key }).promise();

  console.log('Received mocked data:', result.Body?.toString()); // Expected: 'Mocked content!'

  // 3. Restore the original method after the test
  restore('S3', 'getObject');

  console.log('Mock restored. Subsequent calls would use original S3 or fail without credentials.');
})();

view raw JSON →