S3Mock: A Local Amazon S3 API for Integration Tests

What S3Mock does and who it is for

S3Mock is a lightweight server that implements a subset of the Amazon S3 API for local integration testing. It removes the need for real AWS infrastructure during development and testing. The recommended usage is to run it as a Docker container or through Testcontainers, which avoids classpath conflicts with the application under test. It is written in Kotlin with Spring Boot 4.x and runs on the JVM. The project is licensed under Apache License 2.0. It is explicitly a testing tool: the README states that S3Mock is not for production and lacks the security features required for production use.

How S3Mock serves requests

The architecture is a three-layer pipeline. A controller layer exposes REST endpoints over HTTP on port 9090 and HTTPS on port 9191. It delegates to a service layer that holds the business logic, which in turn coordinates a store layer responsible for persistence. The store reads and writes to the local filesystem. The filesystem structure is documented: each bucket is a directory containing bucketMetadata.json, each object is stored under a UUID directory with binaryData and objectMetadata.json, and multipart uploads live under a multiparts directory with per-part files. That structure is an implementation detail and may change between releases, and reusing persisted data across restarts is not officially supported. By default S3Mock deletes all stored data on shutdown; COM_ADOBE_TESTING_S3MOCK_STORE_RETAIN_FILES_ON_EXIT can keep it.

Starting S3Mock and running a first request

The quickest path is the published Docker image and the four commands from the README quick start.

# 1. Start S3Mock
docker run -p 9090:9090 adobe/s3mock

# 2. Create a bucket
aws s3api create-bucket --bucket my-bucket --endpoint-url http://localhost:9090

# 3. Upload a file
aws s3api put-object --bucket my-bucket --key my-file --body ./my-file --endpoint-url http://localhost:9090

# 4. Download the file
aws s3api get-object --bucket my-bucket --key my-file --endpoint-url http://localhost:9090 output-file

For HTTPS, add --no-verify-ssl and use port 9191. The same operations work with cURL, and there are Testcontainers, JUnit 5 and TestNG integrations for programmatic tests. The JUnit 5 and TestNG modules carry a note that they may be removed in S3Mock 6.x, with Testcontainers recommended instead.

Configuration and health checks

Configuration is driven by environment variables. COM_ADOBE_TESTING_S3MOCK_STORE_ROOT sets the base directory for file storage and defaults to the Java temp directory. COM_ADOBE_TESTING_S3MOCK_STORE_REGION defaults to us-east-1. COM_ADOBE_TESTING_S3MOCK_STORE_INITIAL_BUCKETS takes a comma-separated list of buckets to create on startup. COM_ADOBE_TESTING_S3MOCK_STORE_RETAIN_FILES_ON_EXIT controls whether files survive shutdown. COM_ADOBE_TESTING_S3MOCK_STORE_VALID_KMS_KEYS accepts comma-separated KMS key ARNs for validation only, with no actual encryption. COM_ADOBE_TESTING_S3MOCK_CONTROLLER_CONTEXT_PATH sets a base context path. Spring profiles are activated through SPRING_PROFILES_ACTIVE: debug and trace enable verbose logging and the actuator, actuator enables JMX and all Spring Boot Actuator endpoints, and vectors enables the experimental S3 Vectors API. Two readiness endpoints exist. /favicon.ico is always available and returns 200 OK with an empty body, and is used by Testcontainers and the integration test suite. /actuator/health requires the actuator profile.

Supported operations and the gaps

S3Mock implements a large subset of S3 operations, including CreateBucket, PutObject, GetObject, HeadObject, ListObjectsV2, DeleteObject, multipart upload, versioning, object lock, legal hold, retention and tagging. Many operations are marked unsupported, such as bucket policies, replication, encryption configuration, website configuration, CORS, lifecycle, logging, metrics and SelectObjectContent. The full table is in the README. S3 Vectors support is experimental. Because the support matrix is uneven, a test that exercises an unsupported operation will fail in a way that real S3 would not, so the supported list should be checked before relying on S3Mock for a given workflow.

Important limitations

Four constraints shape how S3Mock can be used. Path-style access only: URLs like http://localhost:9090/bucket/key work, but virtual-hosted style http://bucket.localhost:9090/key does not. Presigned URLs are accepted but not validated, so expiration, signature and HTTP verb are not checked. SSL uses a self-signed certificate, so clients must trust it or disable verification. KMS key ARNs are validated but no encryption is performed. Combined with the statement that S3Mock is not for production, these limits make it a test double rather than a storage backend. The performance notes add that disk usage grows with stored data, memory scales with concurrent multipart uploads.

S3Mock versus LocalStack or real AWS

The alternative most teams consider is LocalStack or a real AWS account. S3Mock is focused narrowly on S3 and ships as a Kotlin service with Testcontainers and JUnit 5 integrations. Real AWS removes the fidelity gap entirely but costs money and network access and is slower for unit-level tests. S3Mock's advantage is speed and a simple Docker image on ports 9090 and 9191; its disadvantage is the partial operation support and the path-style restriction. If your tests depend on bucket policies, replication or virtual-hosted URLs, S3Mock will not cover them.

Maintenance, licensing and build requirements

The last push to the default main branch was on 2026-10-14, and recent releases include 5.2.3 on 2026-09-19, 5.2.2 on 2026-09-11 and 5.2.0 on 2026-08-22, so the project is active. The license is Apache 2.0. Building from source requires Java 25 and Docker, while the packaged artifacts run on Java 17 or newer. The version compatibility table shows S3Mock 5.x targets Spring Boot 4.0.x, Kotlin 2.3, Java 17 target and 25 compile, AWS SDK v2 and Testcontainers 2.x, with older major versions deprecated or end of life.

Editorial conclusion

Adopt S3Mock if your tests need an S3-compatible endpoint without AWS infrastructure, and prefer the Docker or Testcontainers route to avoid classpath conflicts. Avoid it for production storage or for clients that require virtual-hosted style URLs, because S3Mock supports path-style access only. Verify first that the operations your code uses are in the supported list and that ports 9090 and 9191 are free.

Frequently asked questions

Official sources

1. adobe/S3Mock on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases