# aws-sdk-mock, swapping AWS SDK methods for stubs in Node tests

> aws-sdk-mock replaces methods on AWS SDK service objects so that a Lambda function under test never reaches AWS, and it does it with Sinon rather than a recording proxy. The whole API is five functions, the library targets the v2 SDK, and it was rewritten in TypeScript for the 6.x line.

**dwyl/aws-sdk-mock** — :rainbow: AWSomocks for Javascript/Node.js aws-sdk tested, documented & maintained. Contributions welcome!

- Repository: https://github.com/dwyl/aws-sdk-mock
- Stars: 1,127 · Forks: 106
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/dwyl-aws-sdk-mock

## A test that must not reach AWS

The module was created to help test AWS Lambda functions, and the project says plainly that it can be used in any situation where the AWS SDK needs to be mocked. The reasoning is about isolation. A stub prevents a specific method from being called directly, and here the method being prevented is the call into a real AWS service, so that the function under test cannot reach the network. That is a different problem from stubbing your own module, and it is the reason this library exists rather than a general mocking tool. The audience is a developer writing unit tests for serverless code, who otherwise has three bad options: supply real credentials, run against a local emulator, or write a bespoke fake of the SDK. The library takes the third option and packages it, which is why its surface is small enough to describe in a page.

## Five functions, and one of them restores everything

The documented API is short. AWS.mock takes a service name, a method name and a replacement, and the replacement can be a string or a function, as in publishing to SNS or writing to DynamoDB. AWS.restore takes an optional service and an optional method, so you can restore one method, all methods of one service, or, if you call it with no arguments, every service and method that is currently mocked, which the documentation describes as a restore all function. AWS.remock updates the replacement on a method that is already mocked, which is the one that matters for a test that changes its fixture between assertions. Two more functions control where the SDK comes from. AWS.setSDK sets the require path for the aws-sdk, aimed at a nested node module, and AWS.setSDKInstance sets the SDK object itself. The names, the service string and the method string, are the whole interface, and a test file that uses them reads like a list of the AWS calls that function is allowed to make.

## Sinon does the patching

The implementation detail that explains the behaviour is that the library uses Sinon.js to mock the AWS SDK services and their associated methods. The package.json confirms it, with sinon at version 22 as a runtime dependency rather than a development one, and aws-sdk itself as a dependency at 2.1231.0 or later, plus neotraverse. Two consequences follow from that choice. First, the mocking is a method substitution on a live object, so the surrounding SDK machinery, the request builders, the parameter validation and the promise wrapping, all still run. Your code path is exercised, only the network call is replaced. Second, because aws-sdk is a runtime dependency, installing this library pulls the entire v2 SDK into your tree even if your application only uses a couple of services, which is a real cost in a project that has already moved most of its code to the modular v3 clients.

## Using it from a test file

Installation is a dev dependency, since it belongs in your test tooling rather than in your shipped code.

```bash
npm install aws-sdk-mock --save-dev
```

In plain JavaScript the pattern is to require the library, mock the methods the code under test calls, and then restore them.

```js
const AWS = require('aws-sdk-mock');

AWS.mock('DynamoDB', 'putItem', function (params, callback){
  callback(null, 'successfully put item in database');
});

AWS.mock('SNS', 'publish', 'test-message');

// S3 getObject mock - return a Buffer object with file data
AWS.mock('S3', 'getObject', Buffer.from(require('fs').readFileSync('testFile.csv')));
```

The three examples cover the three shapes of a replacement. A function receives the parameters and a callback, and the callback style is what the v2 SDK expects. A plain string is a fixed return value. A Buffer stands in for a payload, and reading it from a file in the test fixture is the way to return file data for an S3 getObject. The S3 example also shows a detail worth copying, since a mock that returns the right shape is what makes the assertion meaningful.

## TypeScript needs the SDK instance set explicitly

The TypeScript usage differs in one step that surprises people, which is why the example calls AWSMock.setSDKInstance(AWS) before mocking anything. In the typed example the import is the default export of the library, and the SDK itself is imported separately, and the instance is handed over explicitly before the mock is registered.

```typescript
import AWSMock from 'aws-sdk-mock';
import AWS from 'aws-sdk';
import { GetItemInput } from 'aws-sdk/clients/dynamodb';

AWSMock.setSDKInstance(AWS);
AWSMock.mock('DynamoDB', 'getItem', (params: GetItemInput, callback: Function) => {
  callback(null, {pk: 'foo', sk: 'bar'});
})

const dynamodb = new AWS.DynamoDB({apiVersion: '2012-08-10'});
```

The DocumentClient is covered too, with a mock on DynamoDB.DocumentClient and the get method, and the assertion is made against the promise the SDK returns, so the code under test is still using the real promise wrapper. Two housekeeping details from the examples are worth copying. The beforeAll hook carries a comment that getting anything requires environment variables, which is a reminder that a partially mocked environment still has ambient expectations. And the restore call belongs at the end of the test, because a mock that outlives its test changes the behaviour of the ones after it.

## A TypeScript rewrite with a mixed release history

The 6.x line is a rewrite rather than an increment. Version 6.0.1, published on 2024-05-18, is described as the TypeScript rewrite with a patch to resolve an issue, and it is visible in the repository, where the sources are in src/ with a tsconfig.json, the build runs through tsup, and the published entry points are dist/index.js, dist/index.mjs and dist/index.d.ts. The test setup is TypeScript as well, with mocha running the spec files through ts-node, nyc producing coverage, and tsd checking the type definitions against the test directory. The lint script is tsc, which is a type check rather than a style linter, although an.eslintrc.json and an.npmignore are also present. The version story has a wrinkle. The package.json carries 6.2.2 while the newest release tag listed for the repository is v6.2.0 from 2024-09-11, and that release was a maintenance release updating dependencies to address a published CVE. The last push to the main branch was on 2026-10-19, so work continues on the branch, and the version in the manifest is ahead of the newest tag. The licence is Apache-2.0, which is permissive and leaves the obligations of the SDK and Sinon themselves where they belong.

## The v2 assumption, and what to use instead

The clearest limit is stated in the project documentation itself. The library is best suited to the AWS SDK for JavaScript v2, and for v3 the documentation points at an issue in the repository where the maintainers explain that you might not need this library at all. The reason is structural rather than philosophical. This library patches methods on a service object of the v2 SDK, so its mocking works where the v2 shape applies, while the v3 SDK is modular, with per service clients, and the mock surface is different. The alternative approach in that case is to inject your own client interface into the code under test and pass a fake in tests, which costs a layer of indirection in production code but gives full control over the behaviour, including errors and partial responses. Between the two, the honest comparison is that aws-sdk-mock is zero ceremony for existing v2 code, while a v3 codebase is usually better served by designing for injection, because the library has nothing to patch. There is also a middle option, since a v3 service client can be wrapped in your own thin object, which lets a test substitute a plain object rather than reaching into the SDK.

## Conclusion

aws-sdk-mock fits a team maintaining Lambda functions or worker code against the AWS SDK v2 that wants a unit test to run without credentials, without network and without a local DynamoDB, and it fits a codebase that only needs a handful of methods stubbed rather than a whole service faked. It does not fit a project on the modular AWS SDK v3, where the project documentation itself points you elsewhere, and it does not fit a team that wants recorded or stateful fakes, because the replacement is a fixed value or a callback function rather than a recorded interaction model. Verify three things before adopting it: which SDK major version your code actually imports, whether the method you intend to stub is reachable through the service object the library patches, and how you restore state between tests, since a mock left in place leaks into the next case.

## FAQ

### What does aws-sdk-mock do?

It replaces methods on AWS SDK service objects with a replacement function or string so that code under test never calls the real AWS services. It uses Sinon.js under the hood to perform the mocking.

### How do I install aws-sdk-mock?

Install it as a development dependency with npm install aws-sdk-mock --save-dev, then require it in your test files. The package is published to npm as aws-sdk-mock.

### How do I restore AWS SDK methods after mocking them?

AWS.restore accepts an optional service and an optional method, so it can restore one method, every method of one service, or all mocked services and methods when it is called with no arguments at all.

### Does aws-sdk-mock work with the AWS SDK v3?

The project states the library is best suited to the AWS SDK for JavaScript v2, and points readers to an issue in its repository for the v3 case, noting that you might not need the library there. The mock mechanism patches methods on v2 style service objects.

## Sources

- [dwyl/aws-sdk-mock on GitHub](https://github.com/dwyl/aws-sdk-mock)
- [Issues](https://github.com/dwyl/aws-sdk-mock/issues)
- [License: Apache-2.0](https://github.com/dwyl/aws-sdk-mock/blob/main/LICENSE)
- [README](https://github.com/dwyl/aws-sdk-mock/blob/main/README.md)
- [Releases](https://github.com/dwyl/aws-sdk-mock/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dwyl-aws-sdk-mock