RavenDB Test Driver

ravendb-test-driver runs your integration tests against a real RavenDB server instead of a mock. Each test gets its own isolated database, created on demand and torn down afterwards, so tests do not leak state into one another. You write ordinary ravendb client code; the driver handles the server and the per-test database lifecycle.

Install

pip install ravendb-test-driver

Python 3.10+ is required.

Providing a server: pick one

The driver needs a RavenDB server to talk to. Choose how it should get one based on your environment.

1. Embedded server (default, needs .NET)

Out of the box the driver boots an embedded RavenDB server (via ravendb-embedded). Nothing to configure, but the embedded server is a .NET application, so a matching runtime must be installed:

Check with dotnet --list-runtimes. The requirement tracks the embedded server and can change on a minor upgrade, so re-check it when you bump versions.

2. Self-contained embedded server (no system .NET)

Let the driver download and cache a self-contained RavenDB build. It manages the server for you without calling dotnet:

from ravendb_embedded import ServerOptions
from ravendb_test_driver import RavenTestDriver

options = ServerOptions()
options.with_auto_downloaded_server()
RavenTestDriver.configure_server(options)

The embedded package detects the host operating system and architecture, so the same test configuration is portable across supported Windows, Linux, and macOS machines.

Call configure_server() before the first get_document_store(). The first run downloads 100 MB+; later runs reuse the cache. Self-contained mode needs no system .NET, but normal RavenDB OS dependencies still apply; minimal Linux images may need their distribution's ICU package. See labs/04-embedded-no-dotnet.md.

3. Attach to a server you run yourself (no .NET)

If you would rather not put .NET on the test machine (containerized CI, locked-down hosts), run RavenDB yourself (Docker, testcontainers, a shared CI service) and point the driver at its URL. The driver skips the embedded boot entirely and still creates an isolated database per test.

from ravendb_test_driver import RavenTestDriver

RavenTestDriver.configure_external_server("http://localhost:8080")
# or set RAVENDB_TEST_SERVER_URL in the environment

For HTTPS with client-certificate authentication:

RavenTestDriver.configure_external_server(
    "https://my-ravendb",
    certificate_pem_path="client.pem",
    trust_store_path="ca.crt",  # needed when the server CA is not already trusted
)

The equivalent environment variables are RAVENDB_TEST_SERVER_URL, RAVENDB_TEST_SERVER_CERT, and RAVENDB_TEST_SERVER_CA. Call the configuration method once, before the first get_document_store(). A runnable Docker / testcontainers guide is in labs/01-attach-to-server.md.

Usage

Subclass RavenTestDriver (or hold an instance) and call get_document_store() in each test to get a store backed by a fresh database:

from unittest import TestCase
from ravendb_test_driver import RavenTestDriver


class TestBasic(TestCase):
    def setUp(self):
        self.test_driver = RavenTestDriver()

    def test_stores_a_document(self):
        with self.test_driver.get_document_store() as store:   # isolated database
            with store.open_session() as session:
                session.store({"Name": "John"}, "people/1")
                session.save_changes()

Runnable example: labs/02-embedded-per-test.md.

Seeding data and waiting for indexes

• Override setup_database(self, store) to seed or configure every database the driver hands out (indexes, reference data, and so on).
• get_document_store(options) accepts GetDocumentStoreOptions; set a wait_for_indexing_timeout to block until indexing settles, or call wait_for_indexing(store) yourself.
• wait_for_user_to_continue_the_test(store) opens RavenDB Studio so you can inspect the data mid-test.

Runnable example: labs/03-seeding-indexes.md.

Links

The runnable lab scripts live in this repository and are not installed into site-packages.

• PyPI: https://pypi.org/project/ravendb-test-driver/
• GitHub: https://github.com/ravendb/ravendb-python-testdriver
• Server and self-contained options: https://github.com/ravendb/ravendb-python-embedded