Pure Go Redis server for Go unittests
Pure Go Redis test server, used in Go unittests.
Sometimes you want to test code which uses Redis, without making it a full-blown
integration test.
Miniredis implements (parts of) the Redis server, to be used in unittests. It
enables a simple, cheap, in-memory, Redis replacement, with a real TCP interface. Think of it as the Redis version of net/http/httptest.
It saves you from using mock code, and since the redis server lives in the test process you can query for values directly, without going through the server stack.
There are no dependencies on external binaries, so you can easily integrate it in automated build processes.
Be sure to import v2:
import "github.com/alicebob/miniredis/v2"
Implemented commands:
Since miniredis is intended to be used in unittests TTLs don't decrease
automatically. You can use TTL() to get the TTL (as a time.Duration) of a
key. It will return 0 when no TTL is set.
m.FastForward(d) can be used to decrement all TTLs. All TTLs which become <=
0 will be removed.
EXPIREAT and PEXPIREAT values will be converted to a duration. For that you can either set m.SetTime(t) to use that time as the base for the (P)EXPIREAT conversion, or don't call SetTime(), in which case time.Now() will be used.
SetTime() also sets the value returned by TIME, which defaults to time.Now(). It is not updated by FastForward, only by SetTime.
m.ClockTTL(true) makes TTLs decrease as the clock (time.Now(), or the
SetTime() value) advances, instead of only via FastForward. Expired keys are
removed lazily, whenever a database is accessed via a command or a
Miniredis-level accessor. Combined with SetTime() the expiry stays coherent
with TIME and (P)EXPIREAT. Note that against the wall clock this makes expiry
depend on test execution speed, which is why it's not the default.
miniredis works inside a testing/synctest bubble (Go 1.25+). Since real TCP
connections can't be used there, connect with m.Dial(), which serves the
connection on an in-memory pipe — most redis clients accept it as a custom
dialer. NewMiniRedis() is the non-started constructor: with Dial() no
listener is ever created. Inside a bubble time.Now() is the bubble's fake
clock, so with ClockTTL(true) a plain time.Sleep() expires keys — no
FastForward needed:
synctest.Test(t, func(t *testing.T) {
m := miniredis.NewMiniRedis()
defer m.Close()
m.ClockTTL(true)
client := redis.NewClient(&redis.Options{
Dialer: func(ctx context.Context, _, _ string) (net.Conn, error) {
return m.Dial()
},
})
ctx := context.Background()
client.Set(ctx, "session", "v", time.Hour)
time.Sleep(time.Hour + time.Second) // instant, and deterministic
// key is expired now
})
Miniredis will use math/rand's global RNG for randomness unless a seed is
provided by calling m.Seed(...). If a seed is provided, then miniredis will
use its own RNG based on that seed.
Commands which use randomness are: RANDOMKEY, SPOP, and SRANDMEMBER.
…
Commands which will probably not be implemented:
Integration tests are run against Redis 8.4.0. The ./integration subdir compares miniredis against a real redis instance.
The Redis 6 RESP3 protocol is supported. If there are problems, please open an issue.
If you want to test Redis Sentinel have a look at minisentinel.
A changelog is kept at CHANGELOG.md.
No open issues yet, or sync has not completed.