Engula ClientCompat (Client Compatibility Testing Tool)#

Engula ClientCompat is a Docker-runnable client compatibility verification tool. It packages the official test suites of mainstream Redis community clients into an image, uses the same set of tests to verify both the Redis 7.2 baseline and Engula, and generates an HTML report.

This official guide only covers the Docker image + common run modes + report interpretation. Advanced usage such as building from source, switching client source code, persisting long-term trends, and deep CI integration is maintained in the open-source project documentation.

Security note: You only need to mount the host's Docker socket into the test container when running tests such as jedis, redis-py, and node-redis that require launching additional helper containers. This allows the container to call the host's Docker daemon, so please only do this on a controlled test machine.

1. What This Tool Verifies#

Client compatibility testing answers the question: when an existing Redis client SDK uses Engula as the server, do common behaviors such as connections, commands, transactions, Pipelines, Pub/Sub, Streams, and TLS remain consistent with the Redis 7.2 baseline?

The current image focuses on 4 community clients:

If you just want to quickly confirm Redis command and data structure compatibility, prefer Engula KernelCompat. If you need full delivery acceptance testing, use Engula CodeProof. ClientCompat sits between the two, specifically verifying the real client ecosystem.

2. How Verification Works#

Each client test runs through the same workflow:

1. Start Redis 7.2 inside the container as the baseline service.
2. Run the client's official test suite once and record how the Redis baseline performs.
3. Start Engula in the same test environment.
4. Run again using the same client source code and the same version of the test suite.
5. Parse the JUnit, pytest, Ginkgo, or Mocha results and tally Pass / Fail / Skip per test case.
6. Generate report.html, showing the pass rates of Engula and the Redis baseline, the differing cases, and the log locations.

The default criterion is that the pass rate aligns with the Redis baseline. The report lists both the Redis baseline results and the Engula results, making it easy to determine whether a difference comes from Engula behavior, client test assumptions, or the upstream test environment.

3. Preparation#

The official version runs using a prebuilt Docker image, so you do not need to install Java, Maven, Python, Go, Node.js, or client source code on the host. You only need to prepare:

The go-redis test does not require mounting the Docker socket, making it suitable as a first quick run-through. jedis, redis-py, and node-redis launch helper containers, so they require additionally mounting the Docker socket.

4. Pull the Image#

1docker pull registry.ap-southeast-1.aliyuncs.com/montplex/engula-client-compat:latest

:latest is a multi-architecture image; amd64 and arm64 hosts will automatically pull the matching architecture.

5. Quick Start: Run go-redis First#

go-redis does not require mounting the Docker socket, so its command is the simplest:

1mkdir -p results
2
3docker run --rm \
4  -v "$(pwd)/results:/work/results" \
5  registry.ap-southeast-1.aliyuncs.com/montplex/engula-client-compat:latest \
6  proof test client --sub 2.3 \
7    --results-dir /work/results \
8    --version engula-latest

Here --sub 2.3 corresponds to go-redis, used as a minimal example. For full client verification, you can directly run the command in the next section.

After the run finishes, check the report under the results/ directory in your host's current directory:

1results/
2└── client-2.3-go-redis-logs/
3    └── 20260519T100000/
4        ├── main.log
5        ├── report.json
6        └── report.html

Open report.html in a browser to view this run's pass rate, failed cases, and log index.

6. Run Full Client Verification#

To run all 4 clients at once, use the launch mode with the Docker socket:

1mkdir -p results
2
3docker run --rm --net host \
4  -v /var/run/docker.sock:/var/run/docker.sock \
5  -v /tmp:/tmp \
6  -v "$(pwd)/results:/work/results" \
7  registry.ap-southeast-1.aliyuncs.com/montplex/engula-client-compat:latest \
8  proof test client \
9    --results-dir /work/results \
10    --version engula-latest

This command runs Jedis, redis-py, go-redis, and node-redis in the order built into the image.

For reference, a full run takes about 38 minutes on an M2 machine; actual time will be affected by the network, helper image cache, and Docker resource limits.

Parameter descriptions:

If you only run the go-redis example, you do not need --net host, the Docker socket, or the /tmp binding.

7. View the Results#

After a full run, the results directory looks like:

1results/
2├── client-2.1-jedis-logs/20260519T100000/
3│   ├── main.log
4│   ├── report.json
5│   └── report.html
6├── client-2.2-redis-py-logs/20260519T100500/
7│   ├── main.log
8│   ├── report.json
9│   └── report.html
10├── client-2.3-go-redis-logs/20260519T101200/
11│   ├── main.log
12│   ├── report.json
13│   └── report.html
14├── client-2.4-node-redis-logs/20260519T102000/
15│   ├── main.log
16│   ├── report.json
17│   └── report.html
18└── engula-latest/
19    └── 20260519T103000/
20        ├── client.json
21        ├── report.json
22        └── index.html

Common files:

The reports are static HTML and do not depend on a server. You can open them directly in a browser or archive them as PoC or acceptance materials.

8. How to Interpret the Report#

Each client report displays these core fields:

We recommend focusing on three categories of information:

• Whether the Redis baseline also has failures. If the Redis baseline fails, investigate the client test environment first.
• Failures unique to Engula. These are more likely to represent differences in protocol, command semantics, or test assumptions.
• Whether failed cases stem from the test framework's internal assumptions, such as process paths, temporary directories, or how helper containers are launched.

9. FAQ#

Do I need to manually start Redis or Engula first?#

No. The tool automatically starts and manages the Redis and Engula processes, and cleans up automatically after testing finishes.

Why do some clients require the Docker socket?#

Some clients' official test suites launch helper containers during testing, for example to test clusters, proxies, Sentinel, or TLS scenarios. The test container needs to launch these helper containers through the host's Docker daemon, so /var/run/docker.sock must be mounted.

Why mount /tmp:/tmp?#

Some tests generate temporary configs under /tmp and then mount those configs into helper containers. Mounting /tmp:/tmp ensures the test container and the host's Docker daemon see the same temporary path.

What if the first run is very slow?#

The first run may need to pull helper test images. We recommend first confirming that the host's Docker can pull images normally, then running the full client verification. If you just want to quickly confirm that the toolchain works, you can run the go-redis example first.

What is the relationship between this tool and CodeProof?#

Engula CodeProof is a complete verification suite covering compatibility, clients, performance, stability, migration, platform, and high availability. ClientCompat retains only its client verification capability, with a more focused image and documentation, making it suitable for verifying the client ecosystem independently.