FauxRedis

A controllable, Redis-compatible dummy server implemented in Elixir/OTP, designed specifically for integration testing.

FauxRedis speaks the Redis RESP protocol over TCP, but exposes a rich programmatic API for stubbing, expectations and fault injection – allowing you to simulate everything from normal key-value operations to timeouts, disconnects and protocol errors.

This project is intentionally not a production Redis replacement. It is a test tool with predictable behaviour and powerful mocking.

Name

FauxRedis – a short, memorable name for a fake Redis server aimed at integration tests. Suggested GitHub repo: faux_redis (slug: faux-redis).

Features

• Real TCP server speaking Redis/RESP on a configurable (or random) port.
• Supports multiple simultaneous connections and pipelining.
• Extensible command dispatcher, with built-in support for:
  • PING, ECHO, AUTH, HELLO, SELECT, QUIT, INFO, CLIENT, COMMAND
  • GET, SET, DEL, EXISTS, EXPIRE, TTL, KEYS, SCAN, FLUSHALL
  • HGET, HSET, HGETALL, HMGET, HMSET
  • SADD, SMEMBERS, SREM, SISMEMBER, SSCAN
  • LPUSH, RPUSH, LPOP, RPOP
  • MGET, MSET, INCR, DECR
  • PUBLISH, SUBSCRIBE, UNSUBSCRIBE (simplified)
• Mock/stub engine:
  • Match by command name, arguments, regex, custom predicate ({:fn, fun}), or connection id.
  • Define:
    • constant responses
    • callback functions ({:fun, fn command -> response end})
    • delays ({:delay, ms, response}), timeouts (:timeout) and missing replies (:no_reply)
    • connection closes (:close or {:close, response})
    • protocol errors ({:protocol_error, bytes}) and partial responses ({:partial, [chunks]})
  • Sequential responses per rule.
  • Full call history for assertions.
• Stateful in-memory store:
  • Strings, hashes, sets, lists and TTLs (enough for most ejabberd/XMPP tests).
• ExUnit helper for quick integration in Elixir projects.
• Designed to be fast to start, good for parallel test runs.

Installation

Add to your mix.exs dependencies.

def deps do
  [
    {:faux_redis, "~> 1.0", only: :test}
  ]
end

Then fetch dependencies:

mix deps.get

Basic usage

You usually run FauxRedis as part of your test supervision tree or via the provided ExUnit case template.

Starting manually inside a test

Main options for start_link/1: :port (default 0 = random), :mode (:mock_first, :stateful_only, :mock_only), :name (registered name), :ip (bind address, default {127,0,0,1}), :require_auth?, :password.

test "simple PING/ECHO with random port" do
  {:ok, server} = FauxRedis.start_link(port: 0, mode: :mock_first)

  port = FauxRedis.port(server)

  {:ok, socket} =
    :gen_tcp.connect('localhost', port, [:binary, packet: :raw, active: false])

  payload =
    [
      ["PING"],
      ["ECHO", "hi"]
    ]
    |> Enum.map(&FauxRedis.RESP.encode/1)
    |> IO.iodata_to_binary()

  :ok = :gen_tcp.send(socket, payload)
  {:ok, data} = :gen_tcp.recv(socket, 0, 1_000)

  assert {:ok, "PONG"} = FauxRedis.RESP.decode_exactly(data |> String.split_at(8) |> elem(0))

  :gen_tcp.close(socket)
  FauxRedis.stop(server)
end

Using the ExUnit helper

The library ships with FauxRedis.Case, which starts an isolated server per test and injects redis_server and redis_port into the test context. It also imports convenience stub/3 and expect/3 that take the context map as the first argument (they delegate to FauxRedis.stub/3 / FauxRedis.expect/3).

defmodule MyApp.RedisIntegrationTest do
  use FauxRedis.Case, async: true

  test "basic interaction", %{redis_server: server, redis_port: port} do
    {:ok, _rule} = FauxRedis.stub(server, :get, "value")

    {:ok, socket} =
      :gen_tcp.connect('localhost', port, [:binary, packet: :raw, active: false])

    payload =
      ["GET", "foo"]
      |> FauxRedis.RESP.encode()
      |> IO.iodata_to_binary()

    :ok = :gen_tcp.send(socket, payload)
    {:ok, data} = :gen_tcp.recv(socket, 0, 1_000)
    assert {:ok, "value"} = FauxRedis.RESP.decode_exactly(data)

    :gen_tcp.close(socket)
  end

  test "using context helpers", %{redis_port: port} = ctx do
    {:ok, _rule} = stub(ctx, :ping, "PONG")
    # ...
  end
end

Mocking API

The public API lives in the FauxRedis module:

• start_link/1, child_spec/1
• stub/2 (keyword list: matcher, respond, conn_id/conn_ids, max_calls) and stub/3 (short form)
• expect/3
• calls/1
• reset!/1
• port/1, address/1 (host is always "127.0.0.1" in the returned tuple; bind address is set via :ip in start_link/1)
• stop/1

Low-level RESP helpers: FauxRedis.RESP (encode/1, decode/1, decode_exactly/1, …) for building or parsing wire payloads in tests.

Stubbing a single command

{:ok, server} = FauxRedis.start_link(port: 0)

# Always respond to GET foo with "bar"
{:ok, _rule} =
  FauxRedis.stub(server, {:command, :get, ["foo"]}, "bar")

Sequential responses

# First GET foo -> "one"
# Second GET foo -> "two"
# Third and subsequent GET foo -> nil
{:ok, _rule} =
  FauxRedis.stub(server, :get, ["one", "two", nil])

Fault injection

# PING:
#   1st call -> reply "SLOW" after 500ms
#   2nd call -> no reply (:timeout or :no_reply)
#   3rd call -> close connection
{:ok, _rule} =
  FauxRedis.stub(server, :ping, [
    {:delay, 500, "SLOW"},
    :timeout,
    :close
  ])

Matching by regex, arguments and connection id

# Match any GET whose key starts with "session:"
{:ok, _rule} =
  FauxRedis.stub(server, {:command, :get, [~r/^session:/]}, fn cmd ->
    {:error, "ERR sessions disabled in tests"}
  end)

You can also restrict rules to specific connections via :conn_id or :conn_ids options when calling stub/2/expect/3 (see moduledoc of FauxRedis.MockRule for details).

Inspecting call history

calls = FauxRedis.calls(server)

assert [
         %{
           name: "GET",
           args: ["foo"],
           conn_id: _,
           db: 0,
           timestamp: _,
           rule_id: _,
           action: _
         }
       ] = calls

Resetting between tests

FauxRedis.reset!(server)

This clears:

• all keys and TTLs
• all mock rules and expectations
• call history
• auth and pub/sub state

Using with ejabberd / XMPP

FauxRedis is designed to play nicely with typical Redis clients used by ejabberd and other XMPP systems:

• Start the server on a random port (the default when passing port: 0).

• Ask FauxRedis for the address and use it in ejabberd config:

  {:ok, server} = FauxRedis.start_link(port: 0)
  {"127.0.0.1", port} = FauxRedis.address(server)
  

  Then, in your ejabberd.yml test configuration (or its template):

  redis:
    server: "127.0.0.1"
    port:   <PORT_FROM_FauxRedis.address/1>
  

  Typically you will inject the port via environment variable or a generated config file in your test harness.

• Use the mocking API to simulate:

  • normal key/value behaviour
  • authentication success/failure via AUTH
  • slow Redis ({:delay, ms, inner})
  • completely unavailable Redis (:timeout / :close)
  • protocol-level weirdness ({:protocol_error, bytes}, {:partial, chunks})

Because the server is a normal OTP process, you can run multiple instances in a single test suite to simulate multiple Redis backends if necessary.

SCAN and KEYS pattern matching

SCAN cursor [MATCH pattern] [COUNT count] and KEYS pattern filter keys using Redis glob patterns:

Examples over TCP (RESP arrays):

# Keys whose name contains @ (typical JID-style lookups)
["SCAN", "0", "MATCH", "*@*"]

# Keys ending with a domain suffix
["SCAN", "0", "MATCH", "*@example.com", "COUNT", "100"]

# Same glob rules for KEYS
["KEYS", "session:*"]

FauxRedis applies MATCH filtering before COUNT limits the returned batch. For tests, the cursor is always returned as "0" with the full result set in one reply — enough for clients that loop until cursor zero, but not a faithful reproduction of Redis cursor-based iteration over large keyspaces.

Architectural overview

• FauxRedis.Application – starts a Registry for optional server naming.
• FauxRedis.Command – parsed command struct (name, args, connection id, DB, …).
• FauxRedis.Server – GenServer owning:
  • TCP listener
  • connection registry
  • in-memory store
  • mock rules and call history
  • minimal pub/sub state
• FauxRedis.Connection – per-socket process:
  • buffers incoming bytes
  • decodes RESP frames and pipelines
  • applies response specifications (delays, closes, partials, etc.)
• FauxRedis.RESP – RESP2 encoder/decoder.
• FauxRedis.Store – in-memory Redis-like store.
• FauxRedis.MockRule / MockEngine – rule representation and evaluation.
• FauxRedis.Case – ExUnit helper case template.

Limitations vs real Redis

FauxRedis is not a full Redis implementation. Notable limitations:

• Only a subset of commands is implemented; behaviour of SSCAN, pub/sub, etc. follows this implementation, not every edge case of Redis.
• SCAN / KEYSMATCH patterns use Redis-style glob syntax (*, ?, [...], \ escapes). FauxRedis returns all matching keys in a single page with cursor 0 (no incremental cursor iteration like production Redis).
• Pub/sub semantics are simplified:
  • SUBSCRIBE/UNSUBSCRIBE do not switch the connection into a dedicated pub/sub mode; they manage an internal subscription table and return simple acknowledgements.
  • Messages are pushed as RESP arrays ["message", channel, payload], but not all edge cases of real Redis pub/sub are reproduced.
• Persistence, replication, clustering and scripting are not supported.
• Performance characteristics are tuned for tests, not for production loads.

If you need more real-world behaviour, consider using a real Redis instance for system tests and FauxRedis for fine-grained, deterministic integration tests and fault injection.

Running locally

After cloning the repository:

mix deps.get
mix test

The codebase is compatible with OTP 24 and newer; the CI matrix runs tests on OTP 24, 25 and 26 to keep this guarantee.

License

This project is licensed under the MIT License – see the LICENSE file.