S3Mock is a lightweight server that implements parts of the Amazon S3 API.
It has been created to support hermetic testing and reduces the infrastructure dependencies while testing.
The mock server can be started as a Docker container, through the JUnit4 and JUnit5 support, or programmatically.
Similar projects are e.g.:
Using the Docker image
Starting on the command-line:
docker run -p 9090:9090 -p 9191:9191 -t adobe/s3mock
9090 is for HTTP, port
9191 is for HTTPS.
The mock can be configured with the following environment parameters:
validKmsKeys: list of KMS Key-Refs that are to be treated as valid.
initialBuckets: list of names for buckets that will be available initially.
root: the base directory to place the temporary files exposed by the mock.
Starting with the Docker Maven Plugin
Our integration tests are using the Amazon S3 Client to verify the server functionality against the S3Mock. During the Maven build, the Docker image is started using the docker-maven-plugin and the corresponding ports are passed to the JUnit test through the
AmazonClientUploadIT how it's used in the code.
This way, one can easily switch between calling the S3Mock or the real S3 endpoint and this doesn't add any additional Java dependencies to the project.
Using the JUnit4 Rule
S3MockRuleTest demonstrates the usage of the
S3MockRule, which can be configured through a builder.
To use the JUnit4 Rule, use the following Maven artifact in
<dependency> <groupId>com.adobe.testing</groupId> <artifactId>s3mock-junit4</artifactId> <version>...</version> <scope>test</scope> </dependency>
Using the JUnit5 Extension
S3MockExtension can currently be used in two ways:
@ExtendWith(S3MockExtension.class)and by injecting a properly configured instance of
AmazonS3client and/or the started
S3MockApplicationto the tests. See examples:
S3MockExtensionDeclarativeTest(for SDKv1) or
@RegisterExtensionand by creating and configuring the
S3MockExtensionusing a builder. See examples:
S3MockExtensionProgrammaticTest(for SDKv1) or
To use the JUnit5 Extension, use the following Maven artifact in
<dependency> <groupId>com.adobe.testing</groupId> <artifactId>s3mock-junit5</artifactId> <version>...</version> <scope>test</scope> </dependency>
Using the TestNG Listener
S3MockListenerXMLConfigurationTest demonstrates the usage of the
S3MockListener, which can be configured as shown in
testng.xml. The listener bootstraps S3Mock application before TestNG execution starts and shuts down the application just before the execution terminates. Please refer to
To use the TestNG Listener, use the following Maven artifact in
<dependency> <groupId>com.adobe.testing</groupId> <artifactId>s3mock-testng</artifactId> <version>...</version> <scope>test</scope> </dependency>
Include the following dependency and use one of the
start methods in
<dependency> <groupId>com.adobe.testing</groupId> <artifactId>s3mock</artifactId> <version>...</version> </dependency>
Build & Run
To build this project, you need Docker, JDK 8 or higher, and Maven:
mvn clean install
You can run the S3Mock from the sources by either of the following methods:
- Run or Debug the class
com.adobe.testing.s3mock.S3MockApplicationin the IDE.
- using Docker:
mvn clean package -pl server -am -DskipTests
docker run -p 9090:9090 -p 9191:9191 -t adobe/s3mock:latest
- using the Docker Maven plugin:
mvn clean package docker:start -pl server -am -DskipTests -Ddocker.follow -Dit.s3mock.port_http=9090 -Dit.s3mock.port_https=9191(stop with
Once the application is started, you can execute the
*IT tests from your IDE.
Contributions are welcomed! Read the Contributing Guide for more information.
This project is licensed under the Apache V2 License. See LICENSE for more information.