How do I mock Elasticsearch queries in tests?

Record your application once against a real cluster with Keploy. It captures each search body and the hits, scores, and aggregations the cluster returned, then answers the same queries from that recording with no cluster running.

Is Keploy a Testcontainers Elasticsearch alternative?

For replay, yes. Testcontainers pulls a large image and waits for a green cluster in every job. Keploy records a real cluster once and replays its responses with neither. Keep Testcontainers for exploring new query DSL.

Can Keploy test Elasticsearch aggregations?

Yes. The query body and its computed buckets are captured together, so replay returns exactly what the cluster calculated. Unlike a hand-written stub, the result is tied to the specific aggregation that produced it.

Does Keploy remove the need to wait for an index refresh?

Yes. Elasticsearch only makes documents searchable after a refresh, so tests normally sleep or force one. Recorded responses replay immediately, so indexing tests carry no timing at all.

Does Keploy work with OpenSearch?

Yes. OpenSearch exposes the same REST API surface, so capture and replay are identical — the recorded exchanges are HTTP requests and responses either way.

Is Keploy free to use with Elasticsearch?

Yes. The Keploy CLI is open source under Apache 2.0 and free to run on any service with no seat limits. Nothing is installed into the cluster and no plugin is required.

Keploy as a Elasticsearch testing framework

Keploy mocks Elasticsearch by recording its REST API traffic beneath your client, capturing search hits, aggregations, and index responses exactly as the cluster returned them, then replaying those in tests. No cluster runs in CI and no index has to be created.

Generate Elasticsearch tests free

keploy record -c "./search-service"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a Elasticsearch team

Captured at the Elasticsearch REST API

Keploy records the HTTP exchange beneath your client, so a search replays with the exact hits, scores, and aggregation buckets the cluster computed — not a hand-written approximation of them.

Below the Java, Python, JS, and Go clients
Hits, scores, and _source preserved
Aggregation buckets captured
Bulk index responses recorded

Try Keploy for free Explore the docs

The problem

Why Elasticsearch integration tests slow teams down

The friction is rarely the assertions. It is everything around them — spinning up dependencies, keeping mocks honest, and repairing tests after every refactor.

Book a call Explore the docs

Three ways to do it

Testing Elasticsearch: by hand, with Testcontainers Elasticsearch, or with Keploy

A real cluster gives true relevance and aggregation semantics, at the cost of a heavy container and a refresh wait. Keploy records those responses once and replays them instantly.

By hand

Testcontainers Elasticsearch

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for Elasticsearch vs what Keploy records

All three produce the same assertion. Only the third still passes after the next refactor without anyone editing it.

By hand2–4 hours

search_client_stub.py

hand-written

# Hand-written stub: the query DSL is never parsed.

class StubSearchClient:

def search(self, index, body):

# The body is ignored. This answer is just typed out.

return {

"hits": {

"total": {"value": 1},

"hits": [

{"_id": "ord_1", "_score": 1.0,

"_source": {"state": "NEW", "amount_minor": 4200}},

],

},

}

The query body is discarded, so a wrong field name, a missing analyzer, or an inverted filter returns the expected hits and passes.

Testcontainers Elasticsearch1–2 hours

test_search_real.py

tool-assisted

# Testcontainers Elasticsearch: a real cluster per suite.

import pytest

from elasticsearch import Elasticsearch

from testcontainers.elasticsearch import ElasticSearchContainer

@pytest.fixture(scope="session")

def es():

with ElasticSearchContainer("elasticsearch:8.13.0") as c:

client = Elasticsearch(c.get_url())

client.indices.create(index="orders", mappings=ORDER_MAPPINGS)

yield client

def test_finds_new_orders(es):

es.index(index="orders", id="ord_1", document={"state": "NEW"})

# Near-real-time: without this the search finds nothing.

es.indices.refresh(index="orders")

hits = OrderSearch(es).by_state("NEW")

assert [h["_id"] for h in hits] == ["ord_1"]

Real relevance and mappings — and it needs a large image, a green cluster, an index mapping, and an explicit refresh production never performs.

With Keploy~5 minutes

mocks.yaml

auto-generated

# Recorded with: keploy record -c './search-service'

# The Elasticsearch response, captured at the REST layer.

version: api.keploy.io/v1beta1

kind: Http

name: mock-5

spec:

request:

method: POST

url: /orders/_search

body: '{"query":{"term":{"state":"NEW"}},"size":20}'

response:

status_code: 200

body:

took: 4

hits:

total:

value: 1

relation: "eq"

max_score: 1.2039728

hits:

- _id: "ord_1"

_score: 1.2039728

_source:

state: "NEW"

amount_minor: 4200

The score came from the cluster's own index statistics, and the response is tied to the exact query body that produced it.

Times are estimates for authoring one endpoint’s coverage from scratch, not measurements.

Explore the docs Request a trial

Keploy vs the alternatives

Elasticsearch testing tools, compared

The options a team on caches and search stores actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

Testcontainers

fakeredis

miniredis

redis-mock

Postman

SmartBear ReadyAPI

Best in classStrongPartialNot covered

Assessments reflect each tool’s documented behaviour, not benchmark measurements.

Request a trial Book a call

How it works

Record your Elasticsearch app once, replay it forever

Keploy sits below your Elasticsearch process at the network layer. It watches the calls your app already makes, then serves them back on replay so tests run with no dependencies attached.

Your Elasticsearch appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

Pythonthe elasticsearch-py client

Javathe Elasticsearch Java API client and Spring Data

Node.js@elastic/elasticsearch

Gogo-elasticsearch

+3 more Elasticsearch clients

An example shape of a captured call. Your own endpoints and dependencies come from your real traffic, so nothing here has to be written by hand.

Try Keploy for free Request a trial

Mock coverage

Elasticsearch clients Keploy records, driver by driver

Keploy captures Elasticsearch at the wire protocol, so 5 of these 7 clients need no adapter, no test double, and no Elasticsearch instance in CI.

Auto-mocked
PythonView page
the elasticsearch-py client
Auto-mocked
JavaView page
the Elasticsearch Java API client and Spring Data
Auto-mocked
Node.jsView page
@elastic/elasticsearch
Auto-mocked
GoView page
go-elasticsearch
Auto-mocked
OpenSearch
The same REST API surface, so capture is identical
Partial
.NETView page
Elastic.Clients.Elasticsearch
Partial
RubyView page
the elasticsearch-ruby client

Explore the docs Book a call

Quick start

Your first Elasticsearch test suite in under five minutes

Every command below runs against your existing Elasticsearch service. Nothing in your source tree changes.

1
1Install the Keploy CLI
A single binary. It needs a Linux kernel with eBPF support, or Docker on macOS and Windows — and it adds nothing to your project's dependencies.
curl -sSL https://keploy.io/install.sh | bash
2
2Record your service
Pass the command you already use to start the app. Keploy runs it and watches every socket it opens.
keploy record -c "./search-service"
3
3Exercise the paths you care about
Run the app against your development cluster. Every search and index call, with the response the cluster computed, is captured together.
curl 'localhost:8080/search?state=NEW'
curl 'localhost:8080/search/summary?group_by=state'
4
4Replay in CI
Replay serves the recorded dependency responses, so the job needs no service containers and no Docker daemon.
keploy test -c "./search-service" --delay 10