Redis Memory Server

Common errors

• Command failed with exit code 2: make

  cause The `make` utility is required for compiling the Redis binary but is missing from the system's PATH.
  fix Install `make` on your operating system. For Debian/Ubuntu: `sudo apt-get install build-essential`. For macOS: `xcode-select --install`.

• Error: Redis binary not found

  cause The Redis binary could not be found or successfully downloaded/compiled, or the cache was invalidated without a rebuild.
  fix Run `REDISMS_IGNORE_DOWNLOAD_CACHE=true npm rebuild redis-memory-server` to force a re-download and compilation. Ensure stable internet access and sufficient disk space.

• connect ECONNREFUSED

  cause Your Redis client tried to connect to the RedisMemoryServer before it was fully started or after it was stopped, or with incorrect host/port details.
  fix Always `await redisServer.getHost()` and `await redisServer.getPort()` to ensure the server is ready and you have the correct connection details. Ensure `redisServer.stop()` is called in a `finally` block or test teardown.

Warnings

• gotcha The initial installation or first run of `redis-memory-server` can be significantly slower than subsequent runs because it automatically downloads and compiles the `redis-server` binary. This process requires `make` to be available on your system.
  Fix: Ensure `make` is installed in your development and CI/CD environments. For faster CI, consider caching `node_modules/.cache/redis-binaries`.
• gotcha By default, `redis-memory-server` downloads the 'stable' version of the Redis binary. After the first download, this binary is cached and will not be automatically updated, leading to less deterministic environments and potentially outdated or vulnerable Redis versions across different machines or builds.
  Fix: Explicitly specify a fixed `version` in the `RedisMemoryServer` options (e.g., `{ binary: { version: '6.2.6' } }`) or use `REDISMS_IGNORE_DOWNLOAD_CACHE=true npm rebuild redis-memory-server` to force an update.
• gotcha On Windows, this library uses Memurai instead of Redis. It is currently not possible to specify a particular version of Memurai or Redis when running on Windows.
  Fix: Be aware of potential behavioral differences between Memurai and standard Redis. Plan for testing on Linux/macOS if specific Redis version behavior is critical.
• gotcha Each `RedisMemoryServer` instance starts a full Redis server process, consuming approximately 4MB of memory. While suitable for isolated tests, running a very large number of parallel instances (e.g., hundreds) without careful resource management can lead to high memory consumption.
  Fix: Monitor memory usage in your test environment. Ensure `redisServer.stop()` is always called to release resources. Consider limiting parallel test runners in environments with constrained memory.

Install

• npm install redis-memory-server npm
• yarn add redis-memory-server yarn
• pnpm add redis-memory-server pnpm

Imports

• RedisMemoryServer
  wrong:

  const RedisMemoryServer = require('redis-memory-server')

  correct:

  import { RedisMemoryServer } from 'redis-memory-server'

  The package is primarily ESM-first for Node.js environments (>=18). While CommonJS `require` can be used, it might behave unexpectedly or require specific module configurations depending on your project setup. The class is a named export.
• RedisMemoryServer
  wrong:

  import RedisMemoryServer from 'redis-memory-server'

  correct:

  import { RedisMemoryServer } from 'redis-memory-server'

  The main `RedisMemoryServer` class is a named export, not a default export. Attempting to import it as a default will result in an undefined value.
• RedisMemoryServerOpts
  wrong:

  import { RedisMemoryServerOpts } from 'redis-memory-server'

  correct:

  import type { RedisMemoryServerOpts } from 'redis-memory-server'

  For type-only imports in TypeScript, use `import type` to ensure they are stripped during compilation and do not introduce runtime dependencies or accidental bundling of non-type code.

Quickstart

This quickstart demonstrates how to start a RedisMemoryServer instance, connect to it using ioredis, perform basic set/get operations, and ensure proper cleanup.

import { RedisMemoryServer } from 'redis-memory-server';
import { Redis } from 'ioredis'; // ioredis is a common client, install it separately

let redisServer: RedisMemoryServer | undefined;
let redisClient: Redis | undefined;

async function runRedisTest() {
  redisServer = new RedisMemoryServer({
    binary: {
      version: '6.2.6', // Specify a fixed version for deterministic builds
    },
  });

  try {
    const host = await redisServer.getHost();
    const port = await redisServer.getPort();

    console.log(`Redis server started on ${host}:${port}`);

    redisClient = new Redis({
      host,
      port,
    });

    await redisClient.set('mykey', 'myvalue');
    const value = await redisClient.get('mykey');
    console.log(`Retrieved value: ${value}`); // Expected: 'myvalue'

    await redisClient.del('mykey');
    const deleted = await redisClient.get('mykey');
    console.log(`Value after deletion: ${deleted}`); // Expected: null

  } catch (error) {
    console.error('An error occurred during the test:', error);
  } finally {
    if (redisClient) {
      await redisClient.quit();
      console.log('Redis client disconnected.');
    }
    if (redisServer) {
      await redisServer.stop();
      console.log('Redis memory server stopped.');
    }
  }
}

runRedisTest();