Disposable Qdrant per test run with a fresh collection and deterministic fixtures
The pattern is to give each test run its own Qdrant instance and its own collection, so tests cannot interfere with each other and cannot touch production. The fastest and most reliable way to do this in modern Qdrant is to use the in-memory mode (location=':memory:') via the qdrant-client Python library, which spins up an embedded Qdrant instance in the test process with no Docker, no network, and no cleanup. When you need the full server (to test the REST/gRPC API, snapshots, or clustering), use a Docker container started by the test harness with a unique port and a fresh volume, and tear it down at the end of the run. Both approaches give isolation at the process level, which is what makes integration tests reliable. The key discipline is that every test creates its own collection with a unique name, or the test harness creates and drops a collection per test, so no test can observe another test's data.
The mechanism that makes this reliable is the combination of process isolation and deterministic fixtures. Process isolation means a crash, a leaked collection, or a corrupted index in one test cannot affect another test. Deterministic fixtures mean the test does not depend on external data - it upserts a small, hand-picked set of points with known vectors and known payloads, then asserts on exact expected results. This is the opposite of a test that hits a shared instance and asserts 'results are non-empty', which passes even when the retrieval is completely wrong. The fixture dataset should be small (tens of points, not thousands) so the test runs in milliseconds and so the expected results can be computed by hand and written into the test. For tests that need to be fast and are run on every commit, in-memory mode is the right default. For tests that need to exercise the server's HTTP layer, TLS, or snapshot behavior, a Dockerized Qdrant started once per test session and reused across tests (with unique collections per test) is the right trade-off between speed and coverage.
In-memory mode (location=':memory:'): fastest, no network, embedded, ideal for unit and integration tests of application logic.
Docker per test session: exercises the real HTTP/gRPC server, slower startup, suitable for API-level tests.
Unique collection name per test: prevents cross-test interference on a shared instance.
Deterministic fixtures: small hand-picked datasets with known vectors and payloads, so assertions can be exact.
Teardown: delete collections or stop containers at the end of the test to keep the environment clean.
Avoid shared production: never point tests at a shared instance; use a separate instance or in-memory mode.
Parallel test safety: unique collection names or unique ports allow tests to run in parallel.
The trade-off is between fidelity and speed. In-memory mode is the fastest but does not exercise the network stack, TLS, authentication, or clustering. Docker is slower to start but exercises the real server. For a mature test suite, use both: in-memory mode for the bulk of tests that check application logic (embedding, filtering, ranking), and Docker-based tests for a smaller set of tests that check integration concerns (API contract, authentication, snapshot restore). The common mistake is to point tests at a shared staging instance, which makes them slow, flaky, and impossible to run in parallel, and which risks accidental writes to data that other teams depend on. The second mistake is to use a large fixture dataset, which makes tests slow and makes the expected results impossible to verify by hand. The third mistake is to forget teardown, which leaves collections behind and can cause port conflicts on subsequent runs. Version note: in-memory mode in qdrant-client has been available for several releases and is stable, but the exact API for initializing the client in memory may differ across client versions - check the client documentation for your version. The query_points API replaced the older search API in qdrant-client 1.10+.
Version-dependent: in-memory mode requires the qdrant-client library and runs the Qdrant engine locally in Python; it does not require the Qdrant server binary. The exact initialization API (location=':memory:' versus an older form) has changed across client versions. The query_points API used here is qdrant-client 1.10+; older clients used search() and search_batch(). If your tests depend on server-only features (snapshots, clustering, TLS, authentication), in-memory mode will not cover them and you need a Docker-based test.
0-2 years experience
2-5 years experience
5-8 years experience
8+ years experience
