miniredis

Miniredis implements a real Redis server in pure Go, purpose-built for use inside Go unit tests. It runs in-process alongside your test binary and exposes a genuine TCP interface that any Redis client can connect to, so code under test talks to it exactly as it would talk to production Redis — no mocking layer, no interface abstraction to maintain, and no external redis-server binary to install in CI.

Because the server lives in the same process as the test, you can also bypass the network entirely and assert against stored values directly (s.Get("foo"), s.HGetAll("some")), or manipulate time-based behavior like TTL expiry with FastForward() — something that’s awkward to do reliably against a real Redis instance. It implements a large, actively maintained subset of the Redis command set spanning strings, hashes, lists, sets, sorted sets, streams, pub/sub, transactions, and Lua scripting via EVAL.

What You Get

• A real TCP-speaking Redis server you can start and stop per-test with a single miniredis.RunT(t) call and automatic cleanup
• Direct in-process accessors (Get, HGetAll, Exists, …) for seeding fixtures and asserting on state without a client round-trip
• Manual time control via FastForward(d) and SetTime(t) to deterministically test TTL expiry and time-dependent logic
• Broad command coverage across strings, hashes, lists, sets, sorted sets, streams, pub/sub, transactions, and Lua scripting (EVAL/EVALSHA)
• An integration test suite that runs the same command set against a real Redis binary to catch behavioral drift
• Zero external process dependencies — no need to install or manage a redis-server binary in CI

Common Use Cases

• Unit-testing application code that reads and writes to Redis without spinning up a real Redis container
• Testing cache-expiry and TTL logic deterministically using FastForward() instead of real sleeps
• Verifying pub/sub and transaction (MULTI/EXEC/WATCH) flows in isolation, in-process, per test
• Running fast CI pipelines that avoid provisioning and networking a real Redis service container
• Exercising Lua EVAL/EVALSHA scripting paths in application code without a live Redis dependency

Under The Hood

Architecture The package splits cleanly along two axes: a server/ subpackage (server.go, proto.go) implements the RESP wire protocol and TCP connection lifecycle independent of Redis semantics, while the root package implements Redis command behavior itself, spread across one file per command family (cmd_string.go, cmd_hash.go, cmd_list.go, cmd_stream.go, cmd_scripting.go, and so on) that register handlers against a shared Miniredis/RedisDB state pair defined in miniredis.go and db.go. Supporting data structures — sorted sets, HyperLogLog, geohashing — live in their own files (sorted_set.go, hll.go, geo.go) and are consumed by the relevant cmd_* handlers, keeping the command-dispatch layer thin and the data-structure logic independently testable. Per-connection state (selected DB, transaction queue, auth, pub/sub subscription) is isolated in a connCtx struct threaded through each command call, so concurrent connections don’t share mutable request state beyond the mutex-guarded Miniredis instance itself.

Tech Stack Miniredis is a Go module (go 1.17) with a single external runtime dependency, github.com/yuin/gopher-lua, used to back the EVAL/EVALSHA scripting commands with an embedded Lua interpreter rather than shelling out. Everything else — the RESP protocol parser, the TCP server loop, and all command logic — is implemented against the Go standard library only, with no ORM, web framework, or database driver involved since the package itself acts as the server. A Makefile drives local builds and the integration/ subdirectory scripts fetching and building a real redis-server binary to run comparison tests against.

Code Quality The project has 26 _test.go files, generally one per command family, using only the Go standard library’s testing package rather than a third-party assertion library like testify. Errors from command handlers are returned as typed Redis protocol errors rather than swallowed, matching real Redis error semantics closely enough that client libraries built for production Redis behave the same against it. CI (.github/workflows/ci.yaml) runs the full suite across four Go versions (1.17 through 1.25) and additionally builds and runs a real Redis server for integration comparison, which is a stronger correctness signal than unit tests alone. There’s no linter or formatter step visible in CI beyond go vet/go build.

What Makes It Unique Unlike a mock or a stub, miniredis behaves like Redis at the protocol level — it accepts real client connections over TCP and understands a genuinely large slice of the Redis command surface, including transactions, pub/sub, and Lua scripting, rather than just the handful of commands a typical hand-rolled mock would cover. Its explicit, manual time model (FastForward, SetTime) is also a deliberate departure from real Redis: TTLs don’t decay on wall-clock time, they decay only when the test advances them, which makes expiry logic deterministic and fast to test instead of dependent on real sleeps.