Integration Testing Infrastructure

This document describes how Jedis integration tests are wired up: the Redis test environment, how it is started, how tests discover their servers, and how this maps to CI.

Tips & tricks

Tests do not start Redis. They connect to servers that are already running. The servers are defined by src/test/resources/env/docker-compose.yml, started via make start (Makefile), and described to the tests by src/test/resources/endpoints.json. A test selects a server by name through Endpoints.getRedisEndpoint("<name>") (src/test/java/redis/clients/jedis/Endpoints.java).

• Run integration tests locally: make start version=8.6 && mvn clean verify && make stop.
• Run one test fast: make start version=8.6 then mvn -Dtest=YourIT verify (don't forget make stop).
• Add a new server: add a service to src/test/resources/env/docker-compose.yml (set REDIS_CLUSTER/TLS_ENABLED/TLS_CLIENT_CNS/ports/volumes), then add a matching named entry to src/test/resources/endpoints.json.
• Reference it in a test: Endpoints.getRedisEndpoint("<name>") (src/test/java/redis/clients/jedis/Endpoints.java) → endpoint.getClientConfigBuilder().build().
• TLS in a test: build a truststore from endpoint.getCertificatesLocation() via TlsUtil (src/test/java/redis/clients/jedis/util/TlsUtil.java); certs come from <TEST_WORK_FOLDER>/<env>/work/tls/.
• A test got skipped, not run: its endpoint name is missing from the active endpoints file (src/test/resources/endpoints.json for oss-docker, src/test/resources/endpoints_source.json for oss-source) — you're probably on the oss-source (local) provider.
• Reproducing CI: the test build pins Java 8.

1. The test environment is provided by a shared container

All Redis servers used in tests run inside the redislabs/client-libs-test Docker image, published publicly on Docker Hub. The same image is used across several Redis client libraries (Jedis, Lettuce, redis-py, node-redis, go-redis, …).

The image wraps a chosen Redis version and bootstraps a standalone, replication + sentinel, or cluster topology — optionally with TLS / mTLS and modules — entirely from environment variables. Tags follow the Redis version (e.g. redislabs/client-libs-test:8.6). It is not for production use.

You normally never run it by hand — make start brings up the whole topology via Docker Compose (see §4). But the image is self-contained, so you can launch a single instance directly to experiment:

# standalone on :6379
docker run --rm -p 6379:6379 redislabs/client-libs-test:8.6
# 3-node cluster on :7000-7002
docker run --rm -p 7000-7002:7000-7002 \
  -e REDIS_CLUSTER=yes -e NODES=3 -e PORT=7000 redislabs/client-libs-test:8.6

1.1 Container behaviour

1.2 Volumes & directory conventions

1.3 Generated TLS material

When TLS_ENABLED=yes, the container writes these files to its /redis/work/tls/ directory (surfaced on the host under the work/ mount — see §1.2 — which is where the tests read them from):

The PKCS#12 keystores (*.p12) use the password changeit. Certs are generated once and reused on container restart.

1.4 "Endpoint" definition

An endpoint is a host:port pair for one Redis node (127.0.0.1:6379 non-TLS, 127.0.0.1:6390 TLS). For cluster, every node is an endpoint and the client discovers the rest via CLUSTER NODES.

2. How Jedis defines its environment

Everything lives under src/test/resources/env/.

src/test/resources/env/
├── docker-compose.yml         # all Redis services (standalone/sentinel/cluster/tls/mtls/stack)
├── .env                       # base vars (default REDIS_VERSION, image name, work dir)
├── .env.v6.2 … .env.v8.10     # per-version overrides (just pin REDIS_VERSION)
├── redis1-2-5-8-sentinel/     # one dir per environment
│   ├── config/node-<port>/redis.conf   # mounted read-only into the container
│   └── work/                  # runtime state (TLS certs land in work/tls/)
├── standalone2-sentinel/
├── cluster-unbound/
├── ...

Key .env values:

REDIS_VERSION=8.6.1
CLIENT_LIBS_TEST_IMAGE=redislabs/client-libs-test
REDIS_ENV_CONF_DIR=./                       # base for the :/redis/config mounts
REDIS_ENV_WORK_DIR=/tmp/redis-env-work      # base for the :/redis/work mounts

Each docker-compose.yml service is one client-libs-test container, e.g.:

redis1-2-5-8-sentinel:
  <<: *client-libs-image       # image: ${CLIENT_LIBS_TEST_IMAGE}:${REDIS_VERSION}
  environment: [REDIS_CLUSTER=no, REDIS_CLIENT_USER=deploy,
                REDIS_CLIENT_PASSWORD=verify, TLS_ENABLED=yes]
  ports: ["6379:6379", "6390:6390", "26379:26379", "36379:36379"]
  volumes:
    - ${REDIS_ENV_CONF_DIR}/redis1-2-5-8-sentinel/config:/redis/config:r
    - ${REDIS_ENV_WORK_DIR}/redis1-2-5-8-sentinel/work:/redis/work:rw

The compose file provides the full matrix: standalone (+TLS/+ACL), sentinel, cluster-unbound, cluster-stable (+TLS), standalone-mtls, cluster-mtls, a Redis-Stack service, Toxiproxy (network fault injection), and an explicitly unavailable instance for failover tests.

3. How tests discover servers: endpoints.json

Tests never hardcode hosts. They look up a named entry in src/test/resources/endpoints.json, loaded by Endpoints.getRedisEndpoint(name).

3.1 Schema

{
  "standalone0-tls": {
    "endpoints":     ["rediss://localhost:6390"], // one URI (standalone) or many (cluster)
    "tls":           true,                         // required
    "username":      "default",                    // optional ACL user
    "password":      "foobared",                   // optional
    "tls_cert_path": "redis1-2-5-8-sentinel/work/tls", // optional; resolved under TEST_WORK_FOLDER
    "bdbId":         0                             // optional (Redis Enterprise only)
  }
}

redis:// = plaintext, rediss:// = TLS. Names encode the topology and mode, e.g. standalone0, standalone0-acl, standalone0-tls, standalone0-tls-wronghost (CN-mismatch negative test), cluster-stable, cluster-stable-tls, cluster-mtls, sentinel-standalone0.

3.2 The Java side (src/test/java/redis/clients/jedis/)

Typical usage:

@BeforeAll static void setUp() {
  endpoint = Endpoints.getRedisEndpoint("standalone0-tls");
}
// ...
try (Jedis j = new Jedis(endpoint.getHostAndPort(), endpoint.getClientConfigBuilder().build())) { ... }

mTLS / TLS tests build a truststore from the cert location(s):

trustStorePath = TlsUtil.createAndSaveTestTruststore(name, List.of(endpoint.getCertificatesLocation()), "changeit");
TlsUtil.setCustomTrustStore(trustStorePath, "changeit");

4. Running the tests (Makefile)

Custom image instead of a version: make start CLIENT_LIBS_TEST_IMAGE_TAG=<tag>.

Test selection (JUnit 5 tags + Maven, see pom.xml)

New integration tests must be named *IT — do not use *IntegrationTest or the @Tag("integration") marker. See §5.

Useful flags: -DskipUnitTests=true (CI Docker job runs integration only), -Dtest=<Class#method> to narrow.

5. Test source layout & where to put tests

All test code lives under src/test/java/redis/clients/jedis/. The package root holds the broad client/pool/connection tests; everything else is grouped by area:

src/test/java/redis/clients/jedis/
├── commands/          # command coverage (integration)
│   ├── jedis/         #   against the legacy Jedis API
│   ├── unified/       #   against the UnifiedJedis surface
│   └── commandobjects/
├── search/  json/  timeseries/   # module command tests (integration)
├── tls/               # TLS / mTLS / SSL options (integration, *IT.java)
├── csc/               # client-side caching (integration)
├── failover/          # multi-db / failover (integration, @Tag("failover"))
├── authentication/    # auth + token-based auth
├── mcf/  providers/  executors/  prefix/   # connection/provider internals
├── params/  builders/  resps/              # mostly unit (arg/response objects)
├── mocked/            # pure unit, Mockito-based — no server
├── scenario/          # @Tag("scenario") — long-running, skipped by default
├── examples/          # io.redis.examples — excluded from test runs
├── benchmark/  codegen/                    # excluded from test runs
└── util/              # shared test helpers (TestEnvUtil, TlsUtil, …) — not tests

Unit vs. integration: the rule

What decides whether a test is run by Surefire (unit) or Failsafe (integration) is how the test is marked — its file-name suffix and/or JUnit tag — not which folder it sits in (the runners select by suffix and tag — see §4 and pom.xml).

New integration tests MUST be named *IT. This is the single accepted convention for new code. Failsafe still recognises the older *IntegrationTest name and the @Tag("integration") marker so the many existing classes keep running while they are migrated, but do not use them for new tests — name your class FooIT and nothing else.

Guidance for new tests:

• Integration test → name the file FooIT.java (the only accepted name for new integration tests — not *IntegrationTest, and never @Tag("integration")). Put it in the area package it exercises (commands/…, search/, tls/, etc.). It connects to a server resolved through Endpoints.getRedisEndpoint(...).
• Unit test → add it next to related unit tests (or under mocked/ if it is Mockito-based), name it FooTest, and leave it untagged. It must pass with no Redis running.
• Never put production-required fixtures in examples/, benchmark/, or codegen/ — those packages are excluded from the test run. Shared helpers go in util/ (helpers there are not collected as tests even if named *Test).

6. Two environments: Docker (full) vs. local-from-source (limited)

Selection is via the TEST_ENV_PROVIDER env var, read by TestEnvUtil:

Override the endpoints file directly with REDIS_ENDPOINTS_CONFIG_PATH, and the TLS cert root with TEST_WORK_FOLDER (default /tmp/redis-env-work).

Local-from-source flow

make system-setup    # CI only: build Redis from github.com/redis/redis + the test module (testmodule.so)
make test-local      # = start-local (TEST_ENV_PROVIDER=oss-source) → mvn verify → stop-local

make start-local runs three local redis-server instances and make mvn-test-local forces TEST_ENV_PROVIDER=oss-source, so tests load endpoints_source.json. Endpoints absent there (cluster, sentinel, TLS, mTLS, stack) resolve to a TestAbortedException and are skipped — that is why the local env runs only a subset. Full coverage requires the Docker env.

7. CI workflows (.github/workflows/)

Both clients pin Java 8 for the test build. Use it when reproducing CI.