S3rver: Local S3 Mock Server

3.7.1 · active · verified Sun Apr 19

S3rver is a lightweight, in-memory or file-system-backed server that emulates a significant subset of the Amazon S3 API, designed primarily for local development and testing environments. It allows developers to test S3 interactions without incurring costs or relying on external network requests. The current stable version is `3.7.1`, with development being active and releases addressing bug fixes, performance improvements, and expanding S3 API compatibility. Key differentiators include its focus on being a development-only tool, minimal runtime dependencies, support for programmatic integration into test suites, and simulation of S3's static website hosting capabilities, including website routing rules. It supports common S3 operations like bucket creation/deletion, object CRUD, object tagging, and basic object lifecycle features.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to programmatically start and stop an S3rver instance, create a temporary directory for storage, and interact with it using the AWS SDK for JavaScript v3 to create a bucket, upload an object, and retrieve it.

import S3rver from 's3rver';
import { S3Client, CreateBucketCommand, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteBucketCommand } from '@aws-sdk/client-s3';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

async function runS3rverExample() {
  const port = 4569;
  const tempDir = await mkdtemp(join(tmpdir(), 's3rver-example-'));
  const bucketName = 'my-test-bucket';
  const objectKey = 'hello.txt';
  const content = 'Hello from S3rver!';

  console.log(`Using temporary directory: ${tempDir}`);

  // Initialize S3rver instance
  const s3rver = new S3rver({
    port: port,
    directory: tempDir,
    silent: true, // Suppress S3rver logs for cleaner output
  });

  // Start the S3rver
  await s3rver.run();
  console.log(`S3rver running on http://localhost:${port}`);

  // Configure AWS SDK client to connect to S3rver
  const client = new S3Client({
    region: 'us-east-1', // S3rver does not enforce specific regions
    endpoint: `http://localhost:${port}`,
    credentials: {
      accessKeyId: 'S3RVER', // S3rver's default credentials
      secretAccessKey: 'S3RVER' // S3rver's default credentials
    },
    forcePathStyle: true // Required for S3rver
  });

  try {
    // 1. Create a bucket
    await client.send(new CreateBucketCommand({ Bucket: bucketName }));
    console.log(`Bucket "${bucketName}" created.`);

    // 2. Upload an object
    await client.send(new PutObjectCommand({
      Bucket: bucketName,
      Key: objectKey,
      Body: content,
      ContentType: 'text/plain'
    }));
    console.log(`Object "${objectKey}" uploaded.`);

    // 3. Download the object
    const { Body } = await client.send(new GetObjectCommand({
      Bucket: bucketName,
      Key: objectKey
    }));
    const downloadedContent = await Body?.transformToString();
    console.log(`Downloaded object content: "${downloadedContent}"`);

    // Verify content
    if (downloadedContent === content) {
      console.log('Content verification successful.');
    } else {
      console.warn('Downloaded content mismatch!');
    }

  } catch (error) {
    console.error('S3 operation failed:', error);
  } finally {
    // Clean up: Delete object and bucket
    try {
        await client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: objectKey }));
        await client.send(new DeleteBucketCommand({ Bucket: bucketName }));
        console.log('Cleaned up bucket and object.');
    } catch (cleanupError) {
        console.warn('Error during cleanup:', cleanupError);
    }

    // Stop the server
    await s3rver.close();
    console.log('S3rver stopped.');

    // Remove temporary directory
    await rm(tempDir, { recursive: true, force: true });
    console.log(`Removed temporary directory: ${tempDir}`);
  }
}

runS3rverExample().catch(console.error);

view raw JSON →