diff --git a/Using-S3Proxy-in-Java-projects.md b/Using-S3Proxy-in-Java-projects.md
index a4d5498..e1439b1 100644
--- a/Using-S3Proxy-in-Java-projects.md
+++ b/Using-S3Proxy-in-Java-projects.md
@@ -67,4 +67,38 @@ while (!s3Proxy.getState().equals(AbstractLifeCycle.STARTED)) {
 The S3Proxy Main class and unit tests demonstrate more complicated configurations:
 
 * https://github.com/andrewgaul/s3proxy/blob/master/src/main/java/org/gaul/s3proxy/Main.java
-* https://github.com/andrewgaul/s3proxy/blob/master/src/test/java/org/gaul/s3proxy/AwsSdkTest.java
\ No newline at end of file
+* https://github.com/andrewgaul/s3proxy/blob/master/src/test/java/org/gaul/s3proxy/AwsSdkTest.java
+
+## S3Proxy Junit Rule
+
+The S3Proxy Junit Rule provides a way to write JUnit tests for classes that require the S3 API without  actually using S3. It utilizes S3Proxy under the covers to provide a "bare minimum", easy to use version of S3 that plugs into the JUnit lifecycle by starting the proxy before each test and shutting it down afterwards.
+
+### Example 
+```java
+@Rule
+public S3ProxyRule s3Proxy = S3ProxyRule.builder()
+                   .withCredentials("access", "secret")
+                   .build();
+
+@Test
+public void example() {
+    //set up an AWS S3 client using the rule as an endpoint
+    AmazonS3 s3Client = AmazonS3ClientBuilder
+            .standard()
+            .withCredentials(
+              new AWSStaticCredentialsProvider(
+                new BasicAWSCredentials(s3Proxy.getAccessKey(), s3Proxy.getSecretKey())))
+            .withEndpointConfiguration(
+              new EndpointConfiguration(s3Proxy.getUri().toString(), Regions.US_EAST_1.getName()))
+            .build();
+    s3Client.createBucket("test_bucket");
+    
+    // now perform some operation in your code that you want to test, using the above client
+    myS3Uploader.uploadFile(s3Client, someFile);
+
+    //verify the expected results of the above code
+    List<S3ObjectSummary> summaries = s3Client.listObjects("test_bucket").getObjectSummaries();
+    assertThat(summaries).hasSize(1);
+    assertThat(summaries.get(0).getSize()).isEqualTo(someFile.length());
+}
+```
\ No newline at end of file