mock-aws-s3

What is mock-aws-s3?

The mock-aws-s3 npm package is a mock implementation of the AWS S3 SDK, allowing developers to simulate interactions with AWS S3 in a local environment. This is particularly useful for testing and development purposes without incurring costs or requiring an actual AWS account.

What are mock-aws-s3's main functionalities?

Mocking S3 Bucket Creation

This feature allows you to mock the creation of an S3 bucket. The code sample demonstrates how to create a bucket named 'my-bucket' using the mock-aws-s3 package.

const AWS = require('mock-aws-s3');
const s3 = new AWS.S3();

s3.createBucket({ Bucket: 'my-bucket' }, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Mocking S3 Object Upload

This feature allows you to mock the upload of an object to an S3 bucket. The code sample demonstrates how to upload a string 'Hello, world!' to a bucket named 'my-bucket' with the key 'my-key'.

const AWS = require('mock-aws-s3');
const s3 = new AWS.S3();

const params = {
  Bucket: 'my-bucket',
  Key: 'my-key',
  Body: 'Hello, world!'
};

s3.upload(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Mocking S3 Object Retrieval

This feature allows you to mock the retrieval of an object from an S3 bucket. The code sample demonstrates how to retrieve an object with the key 'my-key' from a bucket named 'my-bucket' and log its content.

const AWS = require('mock-aws-s3');
const s3 = new AWS.S3();

const params = {
  Bucket: 'my-bucket',
  Key: 'my-key'
};

s3.getObject(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data.Body.toString()); // successful response
});

Other packages similar to mock-aws-s3

aws-sdk-mock

The aws-sdk-mock package allows you to easily mock AWS SDK methods for unit testing. It provides a more comprehensive mocking capability for various AWS services, not just S3. Compared to mock-aws-s3, aws-sdk-mock offers broader functionality and can be used to mock other AWS services like DynamoDB, Lambda, etc.

localstack

LocalStack is a fully functional local AWS cloud stack. It provides a local testing environment for AWS services, including S3, DynamoDB, Lambda, and more. Unlike mock-aws-s3, LocalStack runs a local instance of the services, providing a more realistic testing environment but requiring more resources to run.

s3rver

S3rver is a lightweight server that simulates the S3 API. It is designed for testing S3 interactions locally. Compared to mock-aws-s3, s3rver provides a more realistic simulation of the S3 API by running a local server, which can be useful for integration testing.

README

Mock AWS S3 SDK

This is a very simple interface that mocks the AWS SDK for Node.js. The implementation is incomplete but most basic features are supported.

Available:

• createBucket
• deleteBucket
• listObjects
• listObjectsV2
• deleteObjects
• deleteObject
• getObject
• headObject
• putObject
• copyObject
• getObjectTagging
• putObjectTagging
• upload
• getSignedUrl

It uses a directory to mock a bucket and its content.

If you'd like to see some more features or you have some suggestions, feel free to use the issues or submit a pull request.

Release History

• 2021-04-10   v4.0.2   Update dependencies, remove extra log and use proper path concat
• 2020-01-30   v4.0.0   Fix promises and update packages with various contributions.
• 2018-06-16   v3.0.0   Contributions from @benedict-wellard and @telenor-digital-asia adding support for promises and deleteBucket
• 2017-08-11   v2.6.0   Contributions from @pamelafox and @fkleon adding support for listObjectsV2, tagging and more useful debug info returned
• 2017-05-31   v2.5.1   Fix bug when statSync was called on non existing files, spotted by @AllanHodkinson
• 2017-05-20   v2.5.0   Set LastModified on getObject by @stujo, support for custom metadata on get/head by @rgparkins and putObject returns some data on error by @pamelafox
• 2017-02-02   v2.4.0   Account for no existing keys when getting an object by @derPuntigamer
• 2016-06-03   v2.3.0   Add createBucket method and tests by @neilstuartcraig
• 2016-05-25   v2.2.1   Add Size attribute by @aldafu
• 2016-04-25   v2.2.0   Add MaxKey options in listObject by @hauboldj
• 2016-01-18   v2.1.0   Fix markers on listObjects (by @wellsjo) and add send method (by @AllieRays and @IonicaBizau)
• 2015-11-04   v2.0.0   Static basePath configuration, bound params (by @CJNE) and match upload API (by @kyleseely)
• 2015-10-25   v1.1.0   Removed because of potential breaking change with bound params
• 2015-09-24   v1.0.0   Breaking changes and awesome PR to fix API inconsistencies by @irothschild
• 2015-08-27   v0.5.0   Refactor and default options by @whitingj
• 2015-07-28   v0.4.0   Add headObject method by @mdlavin
• 2015-07-21   v0.3.0   Add CommonPrefixes to listObjects by @jakepruitt
• 2015-03-15   v0.2.7   Mock out AWS' config submodule by @necaris
• 2015-03-13   v0.2.6   Partial match support and ContentLength by @mick
• 2015-03-03   v0.2.5   Allow string and fix tests by @lbud
• 2015-02-05   v0.2.4   Fix url encoding for copy by @ahageali
• 2015-01-22   v0.2.3   Support for copyObject
• 2014-02-02   v0.2.1   Support for deleteObject
• 2014-01-08   v0.2.0   Support streams for getObject/putObject
• 2013-10-24   v0.1.2   Fix isTruncated typo
• 2013-10-09   v0.1.1   Add LastModified to listObject
• 2013-08-09   v0.1.0   First release

Example

Instantiate

var AWSMock = require('mock-aws-s3');
AWSMock.config.basePath = '/tmp/buckets/' // Can configure a basePath for your local buckets
var s3 = AWSMock.S3({
	params: { Bucket: 'example' }
});

PutObject/ListObjects

s3.putObject({Key: 'sea/animal.json', Body: '{"is dog":false,"name":"otter","stringified object?":true}'}, function(err, data) {
	s3.listObjects({Prefix: 'sea'}, function (err, data) {
		console.log(data);
	});
});

CreateBucket

var params = { Bucket: 'example' };
s3.createBucket(params, function(err) {
    if(err) {
        console.error(err);
    }
});

DeleteBucket

var params = { Bucket: 'example' };
s3.deleteBucket(params, function(err) {
    if(err) {
        console.error(err);
    }
});