Skip to main content

Redis Mocking and Replay

Speedscale 2.5.1008 and later can mock Redis and Valkey dependencies from recorded traffic. The responder matches each command and its arguments, including binary values, then returns the recorded RESP2 or RESP3 response while the real backend is offline.

Redis mocking is recorded-response playback. It does not create a stateful Redis server. Outcomes such as expiration, Lua execution, and WATCH conflicts come from the recording instead of being recalculated from new in-memory state.

Support​

CapabilitySupportNotes
RESP2 and RESP3FullThe mock responds using the protocol version in the recorded exchange.
Command and argument matchingFullSignatures include the command and arguments, including binary values.
PipelinesFullRecord the complete pipeline so each response is available during playback.
MULTI, EXEC, and WATCHFull with complete historyThe recording must preserve the chronological connection history and connection metadata.
Lua and expiration outcomesRecorded playbackThe recorded result is returned; the script or expiration clock is not executed again.
Pub/Sub, pattern and shard channel subscriptionsFullA subscriber gets the messages a recorded subscriber received. See Pub/Sub.
MONITORNot supportedMonitor mode is rejected.
Replay against a real serverFull for a single-node serverSee Replay against Redis or Valkey.

The release was qualified with Redis 7.4 and Valkey 8 using both RESP2 and RESP3. TLS and ACL configurations, Redis Cluster, Sentinel, and hosted Redis services were not part of that qualification. Contact Speedscale support if your deployment depends on one of those configurations.

Capture Redis with proxymock​

Redis clients use a raw TCP protocol and usually ignore HTTP proxy environment variables. Use --map to make proxymock listen on a local port and forward that connection to Redis.

Start a recording:

proxymock record \
--map 56379=redis://127.0.0.1:6379 \
--out ./recordings

Point the application at the mapped port and run it:

export REDIS_ADDR=127.0.0.1:56379
./my-app

Exercise every command and transaction path that the mock must serve. For transactions, capture the complete history on each connection, including WATCH, MULTI, queued commands, and EXEC. Filtering or independently editing commands can make that history incomplete and prevent the recording from loading.

Stop the recording after the required traffic has been captured.

Run without Redis​

Stop the real Redis backend, then start the mock on the same mapped port:

proxymock mock \
--map 56379=redis://127.0.0.1:6379 \
--in ./recordings \
--no-passthrough

Run the application again with REDIS_ADDR=127.0.0.1:56379. A matching command receives its recorded response without contacting Redis. --no-passthrough prevents an unmatched request from reaching the real backend.

If the mock cannot match a Redis request, it returns an error instead of inventing state. Capture the missing command sequence or restore transaction history that was filtered from the recording.

Pub/Sub​

Apps that use Redis as a lightweight message bus can be recorded, mocked and replayed with their subscriptions. This covers SUBSCRIBE, PSUBSCRIBE and SSUBSCRIBE and their unsubscribe forms, in RESP2 and RESP3.

Capture subscriptions​

Each subscribe or unsubscribe command is recorded with every confirmation the server sent, one per channel or pattern. Each message the server delivers to a subscription is recorded as its own entry, named message, pmessage or smessage with the channel as its location, and the messages of one subscription are kept together in the order they arrived.

In RESP3 the server can push a message between any two replies, and the recording keeps every command paired with its own reply. Other RESP3 pushes, such as client-side caching invalidations, are not recorded. When capture joins a connection that subscribed before it started, as the eBPF collector can, the messages it then sees are recorded as that subscription's.

Mock subscribers​

The mock answers subscribe and unsubscribe commands the way the server would, whether or not the recording has them. Each new subscription then gets the messages a recorded subscriber of the same channel or pattern received, in order and with the gaps the recording had between them. The first message is sent right after the confirmation. When the recording has several subscribers of one channel, such as one per app instance, each new subscriber gets the next one's messages in turn.

Ordinary commands on a RESP3 connection are answered as usual between messages. A RESP2 connection with subscriptions accepts only the subscribe commands, PING, QUIT and RESET, as on the server.

PUBLISH and SPUBLISH from your app get the recorded reply when the recording has the same command. Otherwise the mock answers with the number of live subscribers on the mock that the message would reach. The message itself is not routed to them: subscribers get the recorded messages, which already include any message your app published to itself.

Replay messages to a subscriber​

Replay hands your app the messages it received when it was recorded. The replay does not subscribe for it: the app subscribes to the target server on its own connection, as it does in production, and the replay publishes each recorded message to that server with PUBLISH, or SPUBLISH for a shard channel. A pattern subscription's message is published to the channel that matched. Messages your app published itself replay like any other command.

The app may subscribe a little after the replay starts. While a message reaches no subscriber, the replay publishes it again for up to five seconds. A message that no subscriber received fails with an error reply that names the channel, and later messages to that channel are published once without waiting. The generator's redis.messages_published and redis.messages_unreceived metrics count both outcomes.

Replay against Redis or Valkey​

You can also send the recorded commands to a real Redis or Valkey server. Use it to load test a cache with your app's real command mix, or to check a move from Redis to Valkey or Amazon ElastiCache by replaying the same recording against each and comparing the reports.

warning

Replay runs every recorded write, delete and FLUSHDB against the target, again on every pass of a load test. Point it at a disposable instance that you can reset, never at a shared or production cache.

Choose the Redis traffic as the tests​

By default a replay sends your app's inbound traffic as tests and serves Redis from the mock. To test Redis itself, make the recorded Redis commands the tests with a tests filter. Choose What a Replay Tests explains the filter, and the Speedscale dashboard sets it with Choose replay tests on the snapshot's Traffic tab.

Regression test a server once, with the recorded commands:

REDISCLI_AUTH=<password> proxymock replay \
--in ./recordings \
--tests-filter '(direction IS OUT) AND (tech IS Redis)' \
--test-against redis://localhost:6379/0

Load test it with several virtual users for a fixed time:

REDISCLI_AUTH=<password> proxymock replay \
--in ./recordings \
--tests-filter '(direction IS OUT) AND (tech IS Redis)' \
--test-against redis://localhost:6379/0 \
--vus 10 --for 1m --load-test

An AI coding assistant with the proxymock MCP server can run the same replay. Ask, for example, "Replay the recorded Redis traffic against redis://localhost:6379/0 and list every command that failed."

Connect to the server​

The address is redis://host:port/db, or rediss://host:port/db for TLS. The path is the logical database the replay selects, and it defaults to 0. When the path or generator.redis.database names a database, the recorded SELECT commands are skipped so every command runs there; otherwise they are sent as recorded. Credentials in the address are rejected so they never end up in shell history or reports.

The replay never sends the recording's own AUTH or HELLO credentials. It authenticates every connection with the password from one of these places:

WhereWhat to set
Your machineThe REDISCLI_AUTH environment variable, which redis-cli reads too
The test configgenerator.redis: username (an ACL user, empty for the default user), password, database, tlsMode and connectTimeout
{
"generator": {
"redis": {
"username": "replay",
"password": "${{secret:redis-creds/password}}",
"database": "0",
"tlsMode": "PROTOCOL_TLS_MODE_REQUIRE"
}
}
}

The test config wins over REDISCLI_AUTH, and the database in the address wins over the test config. Prefer a secret reference such as ${{secret:redis-creds/password}} to a typed password: a typed password is saved in plain text with the test config and every report that uses it. Connect to the database explains where a secret reference is read from on your machine and in a cluster. The dashboard's Database credentials form has no Redis tab yet, so set generator.redis in the test config's JSON.

tlsModeWhat it does
Unset or PROTOCOL_TLS_MODE_DISABLEPlain text, unless the address is rediss://, which means PROTOCOL_TLS_MODE_REQUIRE
PROTOCOL_TLS_MODE_PREFERTries TLS and falls back to plain text when the handshake fails
PROTOCOL_TLS_MODE_REQUIREAlways encrypts, without checking the server's certificate
PROTOCOL_TLS_MODE_VERIFY_CAChecks that a trusted CA signed the certificate
PROTOCOL_TLS_MODE_VERIFY_FULLAlso checks that the certificate names the host

Before any load starts, the replay connects once to each Redis server and sends PING. A wrong password stops the replay straight away with the server's WRONGPASS or NOAUTH message instead of failing every command.

What gets replayed​

The recording interleaves your app's connections. The replay opens one live connection for each recorded connection and sends that connection's commands in their recorded order, so transactions, WATCH, SELECT and pipelines keep their meaning. Pipelined commands are sent one at a time, in order, on their connection.

Recorded commandWhat the replay does
Data commands, MULTI, EXEC, DISCARD, WATCH and SELECTSends them as recorded
HELLOSends it with the recorded protocol version and without its AUTH clause, so a RESP3 recording replays as RESP3
AUTHSkipped: each connection authenticates with the replay's own credentials
EVALSHALoads the script with SCRIPT LOAD first when the recording holds its body in an EVAL or SCRIPT LOAD, so a fresh server does not answer NOSCRIPT. Inside MULTI, when the script is not loaded on that connection yet, the command is sent as EVAL instead.
Blocking commands: BLPOP, BRPOP, BRPOPLPUSH, BLMOVE, BLMPOP, BZPOPMIN, BZPOPMAX, BZMPOP, XREAD and XREADGROUP with BLOCK, WAIT, WAITAOFSends them with the timeout capped at one second, because no other client will push what the recording waited for. A recorded timeout of 0 waits forever and is capped too.
Messages a subscription received (message, pmessage, smessage)Publishes each one with PUBLISH or SPUBLISH so your subscribed app receives it again. See Replay messages to a subscriber.
SUBSCRIBE, PSUBSCRIBE, SSUBSCRIBE and their unsubscribe formsSkipped: your app makes its own subscriptions on the target.
MONITOR, QUIT, RESET, SHUTDOWN, DEBUG, replication commands, CLIENT KILL, CLIENT PAUSE and CLIENT REPLYSkipped.

The replay log names each skipped command once, and the generator's redis.commands_skipped metric counts them.

Each replayed command keeps the server's reply in place of the recorded one, so the report shows both. A command scores as failed when the server answers with an error reply, and the report names it by its error code, such as ERROR WRONGTYPE or ERROR NOSCRIPT. Values that differ from the recording, such as counters and timestamps, do not count as failures. Each reply keeps at most 1,000 elements per list, set or map.

At the end of each pass, a transaction or WATCH left open is discarded so the next pass starts clean. Connections stay open between passes.

Limits​

  • Single-node targets only. The replay does not follow cluster MOVED or ASK redirects. It checks INFO cluster before load starts and stops with a message that a single-node target is required when cluster mode is on. Replay against a standalone server, a primary with cluster mode disabled, or one shard's primary.
  • Amazon ElastiCache IAM authentication is not supported yet. Use a password or an ACL user and password.
  • Functions (FCALL) are sent as recorded. The replay does not load libraries with FUNCTION LOAD.
  • A recorded NOSCRIPT is replayed as recorded. Once a script is loaded on the target, a later EVALSHA succeeds even where the recording failed.
  • Pub/Sub replay needs a subscriber. The app under test must be running and subscribed to the target server, or every recorded message fails as not received.
  • Scripts loaded before recording started cannot be loaded for EVALSHA, because the recording does not hold their body. Start recording before your app loads its scripts.

Kubernetes capture and replay​

The eBPF collector can capture Redis traffic from selected Kubernetes workloads. Confirm the decoded commands in the Redis traffic view, create a snapshot that includes the complete connection history, then start a TrafficReplay to run the application against the Redis responder.

Do not confuse the mocked application dependency with the Redis instance that Speedscale can deploy internally for replay coordination. The replayComponents.redis Helm values configure that internal component; they do not select the Redis dependency being mocked.

Older recordings​

Complete recordings created before Redis response mocking was released can work without recapture when they contain connection IDs, connection start times, proxy identity, network endpoints, and complete chronological transaction history. Recapture traffic if those fields or transaction commands are missing.

Loading search...