embedded-redis

Redis embedded server for Java integration testing.

Forked from ozimov, which was forked from kstyrc

Maven dependency

Maven Central:

<dependency>
  <groupId>com.github.codemonstur</groupId>
  <artifactId>embedded-redis</artifactId>
  <version>1.4.0</version>
</dependency>

Usage

Running RedisServer is as simple as:

RedisServer redisServer = new RedisServer(6379);
redisServer.start();
// do some work
redisServer.stop();

You can also provide RedisServer with your own executable:

RedisServer redisServer = new RedisServer(6379, new File("/path/to/your/redis"));

You can also use fluent API to create RedisServer:

RedisServer redisServer = RedisServer.newRedisServer()
  .executableProvider(customRedisProvider)
  .port(6379)
  .slaveOf("locahost", 6378)
  .configFile("/path/to/your/redis.conf")
  .build();

Or even create simple redis.conf file from scratch:

RedisServer redisServer = RedisServer.newRedisServer()
  .executableProvider(customRedisProvider)
  .port(6379)
  .setting("bind 127.0.0.1") // good for local development on Windows to prevent security popups
  .slaveOf("locahost", 6378)
  .setting("daemonize no")
  .setting("appendonly no")
  .setting("maxmemory 128M")
  .build();

Binaries

Redis binaries are included in the library by default.

When no ExecutableProvider is given the code will attempt to discover which OS and Architecture is being used and choose an appropriate binary.

Not all operating systems and architectures are supported. If you find that the default binaries do not work your best approach is to compile your own and configure an ExecutableProvider.

Additional binaries that are not part of the default set are located in src/main/binaries in this project. You can use the ExecutableProvider.newCachedUrlProvider() to make use of them. (currently only 1 binary) Example code how to do this can be found at src/test/java/tools/DownloadUriTest.java.

Setting up a cluster

Our Embedded Redis has support for:

HA Redis clusters with Sentinels and master-slave replication
Sharded Redis clusters with node replication

Using ephemeral ports

A simple redis integration test with Redis cluster on ephemeral ports, with setup similar to that from production would look like this:

public class SomeIntegrationTestThatRequiresRedis {
  private RedisCluster cluster;

  @Before
  public void setup() throws Exception {
    String bindAddress = Inet4Address.getLocalHost().getHostAddress();
    RedisSentinelBuilder sentinelBuilder = RedisSentinel.newRedisSentinel();
    sentinelBuilder.bind(bindAddress);

    //creates a cluster with 3 sentinels, quorum size of 2 and 3 replication groups, each with one master and one slave
    cluster =
            RedisCluster.newRedisCluster()
                    .withSentinelBuilder(sentinelBuilder)
                    .ephemeralServers()
                    .sentinelStartingPort(26400)
                    .sentinelCount(3)
                    .quorumSize(2)
                    .replicationGroup("master1", 1)
                    .replicationGroup("master2", 1)
                    .replicationGroup("master3", 1)
                    .build();
    cluster.start();
  }
  
  @Test
  public void test() throws Exception {
    // testing code that requires redis running
    JedisSentinelPool pool = new JedisSentinelPool("master1", Set.of("localhost:26400", "localhost:26401", "localhost:26402"));
  }
  
  @After
  public void tearDown() throws Exception {
    cluster.stop();
  }
}

For an example of setting up a sharded redis cluster check out the code in RedisShardedServerClusterTest.

Retrieving ports

The above example starts Redis cluster with servers on ephemeral ports and sentinels on ports 26400, 26401 and 26402. You can later get ports of servers with cluster.serverPorts(), sentinels with cluster.sentinelPorts() or all ports with cluster.ports().

Redis version

When not provided with the desired redis executable, RedisServer runs os-dependent executable enclosed in jar. Currently it uses:

Redis 6.2.7 in case of Linux/Unix x86 or arm64 (x86 source, arm64 source)
Redis 6.2.6-v5 in case of Linux/Unix x64 (source)
Redis 6.2.6-v5 in case of OSX x64 or arm64 (x64 source, arm64 source)
Redis 5.0.14.1 in case of Windows x64 (source)

However, you should provide RedisServer with redis executable if you need specific version.

License

Licensed under the Apache License, Version 2.0

Contributors

Krzysztof Styrc (@kstyrc)
Piotr Turek (@turu)
anthonyu (@anthonyu)
Artem Orobets (@enisher)
Sean Simonsen (@SeanSimonsen)
Rob Winch (@rwinch)
Cristian Badila (@cristi-badila)

olivierboudet / embedded-redis