📝 Documentation

Author: tobi-laa

CONTRIBUTING.adoc

@@ -1,22 +1,22 @@
-= Contributing to `spring-boot-embedded-redis`
+== Contributing to `spring-boot-embedded-redis`
 
 `spring-boot-embedded-redis` is released under the Apache 2.0 license.
 Read on if you would like to contribute!
 
-== Code of Conduct
+=== Code of Conduct
 
 This project adheres to the Contributor Covenant xref:CODE_OF_CONDUCT.adoc[code of conduct].
 By participating, you are expected to uphold this code.
 
-== Using GitHub Issues
+=== Using GitHub Issues
 
 This project uses GitHub issues to track bugs and enhancements.
 Please check the following before opening an issue:
 
 * your issue is not a duplicate/is not already addressed by another issue
 * your issue affects the latest available release
 
-== Code Conventions and Housekeeping
+=== Code Conventions and Housekeeping
 
 None of these is essential for a pull request, but they will all help.
 They can also be added after the original pull request but before a merge.
@@ -30,7 +30,7 @@ Depending on the change this might entail unit tests, integration tests or both.
 This project breaks at less than 100% code coverage, so this is a must.
 * Keep your feature branch up-to-date with `main`.
 
-== Building from Source
+=== Building from Source
 
 The project can be built from the root directory using:
 
@@ -39,7 +39,7 @@ The project can be built from the root directory using:
 gradle clean build
 ----
 
-== Releases
+=== Releases
 
 Releases are automatically built and published to Maven Central once a tag following the semantic versioning pattern is pushed (i.e. `v1.0.0`).
 

README.adoc

@@ -5,4 +5,81 @@ link:./LICENSE[image:https://img.shields.io/badge/License-Apache%202.0-orange[Ap
 image:https://sonarcloud.io/api/project_badges/measure?project=tobias-laa_spring-boot-embedded-redis&metric=alert_status[Quality Gate Status,link=https://sonarcloud.io/summary/new_code?id=tobias-laa_spring-boot-embedded-redis]
 image:https://sonarcloud.io/api/project_badges/measure?project=tobias-laa_spring-boot-embedded-redis&metric=coverage[Coverage,link=https://sonarcloud.io/summary/new_code?id=tobias-laa_spring-boot-embedded-redis]
 
-= Spring Boot `embedded-redis`
+= Spring Boot `embedded-redis`
+
+This library provides an easy way to run an embedded Redis server in your Spring Boot integration tests.
+It mainly acts as a glue between the https://github.com/codemonstur/embedded-redis[`embedded-redis`] library and Spring Boot.
+
+== Usage
+
+To use the library, add the following dependency to your `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.github.tobi-laa</groupId>
+    <artifactId>spring-boot-embedded-redis</artifactId>
+    <version>1.0.0</version>
+    <scope>test</scope>
+</dependency>
+----
+
+You can then declaratively start and stop the embedded Redis server in your integration tests using the `@EmbeddedRedisStandalone` annotation:
+
+[source,java]
+----
+@EmbeddedRedisStandalone
+@SpringBootTest
+class MyIntegrationTest {
+
+    @Autowired
+    private RedisTemplate<String, String> redisTemplate;
+
+    @Test
+    void testSomething() {
+        redisTemplate.opsForValue().set("key", "value");
+        assertThat(redisTemplate.opsForValue().get("key")).isEqualTo("value");
+    }
+}
+----
+
+This will start an embedded Redis server before the Spring context corresponding to the test class is loaded for the first time and stop it after the context is closed.
+The necessary Spring Data Redis properties are automatically set.
+
+You can also use the `@EmbeddedRedisShardedCluster` annotation to start an embedded Redis cluster:
+
+[source,java]
+----
+@EmbeddedRedisShardedCluster
+@SpringBootTest
+class MyIntegrationTest {
+    // ...
+}
+----
+
+There is also the possibility to start the embedded Redis server in high availability mode with replicas and sentinels using the `@EmbeddedRedisHighAvailability` annotation:
+
+[source,java]
+----
+@EmbeddedRedisHighAvailability
+@SpringBootTest
+class MyIntegrationTest {
+    // ...
+}
+----
+
+By default, data stored in the embedded Redis server is flushed after each test method.
+You can disable this behavior by annotating your test class with `@RedisFlushAll(mode = Mode.AFTER_CLASS)` or `@RedisFlushAll(mode = Mode.NEVER)`.
+
+The embedded Redis instances will be started on free ports found starting at the default ports (that is, `6379` or `26379` for sentinels) and be bound to `localhost` by default.
+
+Using an embedded Redis does not break Spring's context caching.
+If you have some integration tests running without an embedded Redis and some with, you will however end up with two different contexts as the properties of the Spring context are modified.
+
+== Acknowledgements
+
+This library is heavily inspired by the awesome https://github.com/maciejwalkowiak/wiremock-spring-boot[WireMock Spring Boot] library.
+
+Furthermore, this library would of course not exist without the https://github.com/codemonstur/embedded-redis[`embedded-redis`] library.
+
+include::CONTRIBUTING.adoc[]