Forem: Preston Vasquez

Mocking MongoDB Go Driver V2: How to Do It (and Why You Probably Shouldn't)

Preston Vasquez — Tue, 17 Jun 2025 20:18:08 +0000

MongoDB Go Driver V1 included the mtest package allowing developers to mock driver responses in memory. A few popular blog posts since emerged detailing how to do this, including "How I'm testing MongoDB calls in Go (for now)" by Liza Shulyayeva. In V1, GODRIVER-1767 marked mtest unstable so that the driver team could alter the API to accommodate new testing requirements. In V2, GODRIVER-2724 internalized mtest making the V1 solution for mocking using mtest unavailable.

Mocking can be overly complex and is brittle (AKA “Mock Hell”). Tests should be focused on your code, not the internals of the Go Driver. Since mocks are not identical to your live environment, problems can stay hidden longer. By the time an issue shows up in production, fixing it can be far more costly than if you’d caught it earlier in a more realistic test. Instead, it's better to use a container-based integration testing framework like testcontainers:

func TestMyRepositoryFunction(t *testing.T) {
    ctx := context.Background()

    //  Start up a MongoDB container
    req := testcontainers.ContainerRequest{
        Image:        "mongo:latest",
        ExposedPorts: []string{"27017/tcp"},
        WaitingFor:   wait.ForLog("Waiting for connections").WithStartupTimeout(30 * time.Second),
    }
    mongoC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })
    require.NoError(t, err)
    defer mongoC.Terminate(ctx)

    // Get mapped host & port
    host, err := mongoC.Host(ctx)
    require.NoError(t, err)
    port, err := mongoC.MappedPort(ctx, "27017")
    require.NoError(t, err)

    // Connect with the Go driver
    uri := fmt.Sprintf("mongodb://%s:%s", host, port.Port())
    client, err := mongo.Connect(options.Client().ApplyURI(uri))
    require.NoError(t, err)
    defer client.Disconnect(ctx)

    err := MyRepositoryFunction(context.TODO(), client.Database("mydb").Collection("mycoll"))
    assert.NoError(t, err, "Should have successfully run")
}

For necessary edge cases V2 provides a MockDeployment option in the experimental API which may be modified or removed without notice. Here is a re-worked example from this StackOverflow answer for V2:

func TestMyRepositoryFunction(t *testing.T) {
    mockDep := drivertest.NewMockDeployment()

    mockDep.AddResponses(
        bson.D{{Key: "ok", Value: "1"}},
        bson.D{
            {Key: "ok", Value: "1"},
            {Key: "value", Value: bson.M{"_id": "custom123", "key": 24}},
        })

    opts := options.Client()
    opts.Deployment = mockDep

    client, err := mongo.Connect(opts)
    require.NoError(t, err)
    defer client.Disconnect(ctx)

    err := MyRepositoryFunction(context.TODO(), client.Database("mydb").Collection("mycoll"))

    assert.NoError(t, err, "Should have successfully run")
}

Mocking an LLM Embedder Targeting MongoDB Atlas

Preston Vasquez — Mon, 09 Sep 2024 15:43:50 +0000

Implementation library: https://github.com/prestonvasquez/vectormock

Problem. Integration testing vector databases with live embedding models can be tricky since results may not always be deterministic. For example, three consecutive similarity searches for "South American Authors" might return:

{text: "Gabriel García Márquez", score: 0.80} # Search 1
{text: "Gabriel García Márquez", score: 0.82} # Search 2
{text: "Gabriel García Márquez", score: 0.78} # Search 3

Suppose we expect the above similarity search to result in a score of 0.8. A common instinct to resolve false negatives (i.e. the 0.82 and 0.78 cases) would be to define an acceptable range for similarity scores:

def is_score_in_range(doc, lower, upper):
    return lower <= doc.score <= upper

class TestSimilarityScore(unittest.TestCase):
    def test_doc_scores(self):
        docs = [{"score": 0.80}, {"score": 0.82}, {"score": 0.78}]
        for doc in docs:
            # If we expect 0.80, then the delta = 2.
            self.assertTrue(is_score_in_range(doc, 0.78, 0.82))

Of course, we are met with a difficult question: how do you set the delta? Large deltas increase false positives; small deltas increases false negatives:

# Wouldn't pass with delta=2
{text: "Gabriel García Márquez", score: 0.779}

# Would pass with delta=40
{text: "Gabriel García Márquez", score: 0.41}

Additionally, embedding models may have rate limits, quotas, or per-usage fees. All of which add to the difficulty of maintaining robust tests.

Goal. This article shows how to overcome these obstacles by mocking an embedding model for MongoDB Atlas, making integration tests more predictable and reliable. For example, say we want the query "South American Authors" to always return the following three documents (without variation) for a vector database integration test:

{text: "Gabriel García Márquez", score: 0.80}
{text: "Gabriela Mistral", score: 0.94}       
{text: "Miguel de Cervantes", score: 0.07}

This guide is specifically focused on similarity scores derived through the dot product.

To simplify things, we'll focus on LangChain's definition of an embedding model, which requires the implementation of two key functions: embed_query and embed_documents.

Deriving embed_query. The goal of an embedding model (embedder) is to transform $N$ -queries to $N$ $n$ -dimensional vectors (an embedding) such that the relationships between different inputs are preserved in the embedding space.

So let $q$ be a mapping from a query vector $v∗\mathbf{v}^{*}$ to a set of similar vectors defined as the column space of $E∈Rn×N\mathbf{E} \in \mathbb{R}^{n\times N}$ , up-to the similarity score algorithm (e.g. dot product).

\begin{equation} q:\mathbf{v}^* \rightarrow \text{C}(\mathbf{E}) \end{equation}

We want to define $v∗\mathbf{v}^*$ such that the following holds for all $v∈C(E)\mathbf{v} \in \text{C}(\mathbf{E})$ :

v∗⋅v=S^ \begin{equation} \mathbf{v}^{*} \cdot \mathbf{v} = \hat{S} \end{equation}

Where $S^\hat{S}$ is derived from normalizing the similarity score. For example, Atlas Vector Search uses the following algorithm to normalize the score using dot product:

\begin{equation*} S = \frac{1}{2}\left(1+ \mathbf{v}^{*} \cdot \mathbf{v}\right) \end{equation*}

Therefore, $S^=2S−1\hat{S}=2S - 1$ .

Using our example, let $vA∗\mathbf{v_A}^*$ be the query vector for "South American Authors". For simplicity, embeddable documents are just a tuple $(P,S)\left(P, S\right)$ where $P$ is the textual representation of a vector in $C(E)\text{C}(\mathbf{E})$ and $S$ is the desired score as it relates to the query vector. If we call $ϕ\phi$ the mock transformer, then let $v1,v2,v3\mathbf{v}_1, \mathbf{v}_2, \mathbf{v}_3$ be the embeddings for Márquez, Mistral, and Cervantes respectively. Without loss of generality:

\begin{equation*} \phi\left(\text{M\'{a}rquez}, 0.80\right) \rightarrow \mathbf{v}_1 \quad \text{such that} \quad \mathbf{v_A}^* \cdot \mathbf{v}_1 = 0.6 \end{equation*}

And to complete the mock embedding, we want:

\begin{equation*} q\left(\mathbf{v_A}^{*}\right) \to \left[\mathbf{v}_1, \mathbf{v}_2, \mathbf{v}_3 \right] \end{equation*}

Looking at libraries like LangChain, $q$ is analogous to similarity_search and $ϕ\phi$ is embed_documents. $C(E)C(\mathbf{E})$ is a subset of the vector store (e.g. a MongoDB collection) and if it was embedded by text-embedding-3-small, for example, $N$ would be $1536$ . Additionally, since $vA∗\mathbf{v_A}^*$ is fixed, then embed_query is simply an accessor:

def embed_query(self, context, text):
    # Return the query vector stored in the object (emb.query_vector)
    return self.query_vector, None

The next step is to define an algorithm for deriving $ϕ\phi$ . But before we get into that, enjoy this (https://xkcd.com/1838/):

Deriving embed_documents. Generally, $ϕv∗\phi^{\mathbf{v}^{*}}$ maps a document $(P,S)\left(P, S\right)$ to a vector $v\mathbf{v}$ such that $v∗⋅v=2S−1\mathbf{v}^{*} \cdot \mathbf{v} = 2S - 1$ :

\begin{equation} \phi^{\mathbf{v}^{*}}: \left(P, S\right) \rightarrow \mathbf{v} \quad \text{such that} \quad \mathbf{v}^* \cdot \mathbf{v} = 2S - 1 \end{equation}

In other words, $ϕv∗\phi^{\mathbf{v}^{*}}$ is used to generate the vectors that compose $E\mathbf{E}$ from (eq. 1). By definition (eq. 2), since $Rank(E)=N\text{Rank}(\mathbf{E}) = N$ and the dimension of $C(E)\text{C}(\mathbf{E})$ is also $N$ , the vectors in $C(E)\text{C}(\mathbf{E})$ must be linearly independent. Therefore defining $ϕv∗\phi^{\mathbf{v}^{*}}$ can be simplified into two conditions that must both hold:

All vectors in the set $v1,v2,…,vN,v∗{\mathbf{v_1}, \mathbf{v_2}, \ldots, \mathbf{v_N}, \mathbf{v^*}}$ are linearly independent (Algorithm A2).
$v⋅v∗=2Sv−1\mathbf{v} \cdot \mathbf{v^*} = 2S_{\mathbf{v}} - 1$ , where $v∈C(E)\mathbf{v} \in \text{C}(\mathbf{E})$ (Algorithm A3).

Without loss of generality, to satisfy condition 1, we need at least one $v_i$ such that the following does not hold:

\begin{equation*} \frac{v_1}{v_1^*} = \frac{v_2}{v_2^*} = \ldots = \frac{v_{n-1}}{v_{n-1}^*} \end{equation*}

This ensures that $v\mathbf{v}$ is not a scalar multiple of $v∗\mathbf{v}^*$ . To guarantee condition 2 is met, we update $v_n$ :

\begin{equation} v_n = \frac{1}{v_n^*} \left(2S - 1 - \sum_{i=1}^{n-1} v_i^*v_i \right) \end{equation}

One very important note: this method will not guarantee the final element falls in the range of $[- 1, 1]$ . This is not a requirement in MongoDB Atlas, which is why we don't worry about normalizing it in this guide.

Finally, it follows that algorithm for mocking embed_documents becomes this:

def embed_documents(ctx, emb, texts):
    vectors = []

    for text in texts:
        # If the text doesn't exist in the document set, return a zero vector
        if text not in emb["docs"]:
            vectors.append([0.0] * len(emb["query_vector"]))
            continue

        # If the vector already exists, return the existing one
        if text in emb["doc_vectors"]:
            vectors.append(emb["doc_vectors"][text])
            continue

        # Otherwise, generate a new orthogonal vector
        new_vector_basis = new_orthogonal_vector(len(emb["query_vector"]), *existing_vectors(emb))

        # Update the last element of the vector so that 
        # v^* * v = 2S - 1.
        doc = emb["docs"][text]
        new_vector = new_score_vector(doc["Score"], emb["query_vector"], new_vector_basis)

        # Store and return the new vector
        vectors.append(new_vector)
        emb["doc_vectors"][text] = new_vector

    return vectors

Example. Lets generate $E\mathbf{E}$ for our "South American Author" example. For simplicity, say $n = 3$ . First we generate the query vector using Algorithm A1:

\begin{equation*} \mathbf{v}_A^{*} = (-0.5, 0.25, 0.71) \end{equation*}

Using new_orthogonal_vector from Algorithm A2, create a vector orthogonal to $vA∗\mathbf{v}_A^{*}$ for Márquez:

\begin{equation*} \mathbf{v}1 = (0.6, -0.8, v{13}) \end{equation*}

From eq. 3 it follows that we need to update $v_{13}$ such that $vA∗⋅v1=0.6\mathbf{v}_A^{*} \cdot \mathbf{v}_1 = 0.6$ . Using eq. 4 we get that

\begin{equation*} \mathbf{v}{A}^{*} \cdot \mathbf{v}_1 = (-0.5)(0.6) + (0.25)(-0.8) + (0.71)(v{13}) \end{equation*}

Substituting the known values:

\begin{equation*} -0.3 - 0.2 + 0.71 v_{13} = 0.6 \end{equation*}

Solving for $v_{13}$ :

\begin{equation*} 0.71 v_{13} = 1.1 \implies v_{13} = \frac{1.1}{0.71} \approx 1.549 \end{equation*}

Thus, the updated vector $v1\mathbf{v}_1$ is:

\begin{equation*} \mathbf{v}_1 = (0.6, -0.8, 1.549) \end{equation*}

See here for a working example using LangChainGo. Note, this will require a MongoDB Atlas Cluster with a vector search index. Check out the tutorial!

Algorithms. Here is a list of algorithms used to mock an embedding model.

A1. Create a vector of normalized 32-bit floats

def new_normalized_float32():
    try:
        # Generate a random integer in the range [0, 2^24)
        max_value = 1 << 24
        n = random.randint(0, max_value - 1)

        # Normalize it to the range [-1, 1]
        normalized_float = 2.0 * (float(n) / max_value) - 1.0

        return normalized_float
    except Exception as e:
        raise Exception("Failed to normalize float32") from e

def new_normalized_vector(n):
    vector = [0.0] * n
    for i in range(n):
        vector[i] = new_normalized_float32()

    return vector

A2. Create $N$ $n$ -dimensional normalized vectors

# Compute the dot product between two lists (vectors) of floats.
def dot_product(v1, v2):
    sum = 0.0
    for i in range(len(v1)):
        sum += v1[i] * v2[i]
    return sum

# Use Gram-Schmidt to return a vector orthogonal to the basis,
# assuming the vectors in the basis are linearly independent.
def new_orthogonal_vector(dim, *basis):
    candidate = new_normalized_vector(dim)

    for b in basis:
        dp = dot_product(candidate, b)
        basis_norm = dot_product(b, b)

        for i in range(len(candidate)):
            candidate[i] -= (dp / basis_norm) * b[i]

    return candidate

# Make n linearly independent vectors of size dim.
def new_linearly_independent_vectors(n, dim):
    vectors = []

    for _ in range(n):
        v = new_orthogonal_vector(dim, *vectors)
        vectors.append(v)

    return vectors

A3. Update two linearly independent vectors such that their dot product is a desired value.

# Update the basis vector such that qvector * basis = 2S - 1.
def new_score_vector(S, qvector, basis):
    sum_value = 0.0

    # Populate v2 up to dim-1.
    for i in range(len(qvector) - 1):
        sum_value += qvector[i] * basis[i]

    # Calculate v_{2, dim} such that v1 * v2 = 2S - 1:
    basis[-1] = (2 * S - 1 - sum_value) / qvector[-1]

    # If the vectors are not linearly independent, regenerate the dim-1 elements of v2.
    if not linearly_independent(qvector, basis):
        return new_score_vector(S, qvector, basis)

    return basis

Dockerizing a MongoDB Replica Set With TLS/SSL

Preston Vasquez — Mon, 07 Nov 2022 16:50:06 +0000

Introduction

The goal of this guide is to create a local SSL-enabled MongoDB Replica Set using docker-compose.

TL;DR: Here is a demo repository.

Prerequisites

Docker is the only pre-requisite, but if you want to connect to the mongo shell locally (recommended) you will need MongoDB.

File Structure

Here is the file structure used in this tutorial:

.db/
config/
├─ mongodb.conf
ssl/
├─ ca.pem
├─ server.pem
docker-compose.yml
init.sh
run.sh
wait-for-mongo.sh

.db/*

This is the database path for the mongod configuration and should be generated automatically by docker-compose.

ssl/*

The files ssl/ca.pem and ssl/server.pem are the TLS CA file and TLS certificate key file, respectively. The data in the ssl/ directory is used by the configuration file to initialize a MongoDB server with SSL enabled. This directory will be volumized on the Docker container for the primary replicant.

This tutorial assumes prior knowledge of TLS/SSL as well as access to valid certificates. For more information on generating certificates using openssl, see this guide.

config/mongodb.conf

This is the configuration file used to configure the mongod instance at startup and will be be volumized on the Docker container for the primary replicant:

net:
  ssl:
    mode: requireSSL
    PEMKeyFile: "/data/ssl/server.pem"
    CAFile: "/data/ssl/ca.pem"
storage:
  dbPath: "/data/db"
net:
  bindIp: 127.0.0.1
  port: 27017

docker-compose.yml

In our docker-compose file, we create three nodes: mongo1 (primary), mongo2, and mongo3. These replicant containers use the bridge network mongo_network.

version: '3'

networks:
  mongo_network:
    driver: bridge

services:
  mongo1:
    hostname: mongo1
    image: mongo
    ports:
      - 27017:27017
    restart: always
    entrypoint: [ "/usr/bin/mongod", "--config", "/data/config/ssl.conf", "--bind_ip_all", "--replSet", "dbrs" ]
    networks:
      - mongo_network
    volumes:
      - ./.db/mongo1:/data/db
      - ./wait-for-mongodb.sh:/scripts/wait-for-mongodb.sh
      - ./init.sh:/scripts/init.sh
      - ./ssl:/data/ssl
      - ./config:/data/config
    links:
      - mongo2
      - mongo3

  mongo2:
    hostname: mongo2
    image: mongo
    ports:
      - 27018:27017
    restart: always
    entrypoint: [ "/usr/bin/mongod", "--bind_ip_all", "--replSet", "dbrs" ]
    networks:
      - mongo_network
    volumes:
      - ./.db/mongo2:/data/db
      - ./wait-for-mongodb.sh:/scripts/wait-for-mongodb.sh

  mongo3:
    hostname: mongo3
    image: mongo
    ports:
      - 27019:27017
    restart: always
    entrypoint: [ "/usr/bin/mongod", "--bind_ip_all", "--replSet", "dbrs" ]
    networks:
      - mongo_network
    volumes:
      - ./.db/mongo3:/data/db
      - ./wait-for-mongodb.sh:/scripts/wait-for-mongodb.sh

Before composing, it is recommended to update the /etc/hosts file to include the replicant mappings:

# Replica set mappings
127.0.0.1 mongo1
127.0.0.1 mongo2
127.0.0.1 mongo3

init.sh

This shell file is used to initialize the replica set and will be ran in the docker container for the primary node (i.e. mongo1, defined in the "docker-compose.yml" section).

#!/bin/bash

mongosh --tls \
  --tlsCAFile /data/ssl/ca.pem \
  --tlsCertificateKeyFile /data/ssl/server.pem <<EOF
var config = {
    "_id": "dbrs",
    "version": 1,
    "members": [
        {
            "_id": 1,
            "host": "mongo1:27017",
            "priority": 3
        }
    ]
};
rs.initiate(config, { force: true });
rs.status();

var config = {
    "_id": "dbrs",
    "version": 1,
    "members": [
        {
            "_id": 2,
            "host": "mongo2:27017",
            "priority": 2
        },
        {
            "_id": 3,
            "host": "mongo3:27017",
            "priority": 1
        }
    ]
};
rs.initiate(config, { force: true });
rs.status();
EOF

wait-for-mongo.sh

This script will wait for a mongo server to come up

#!/bin/bash

NAME=$1
OPTS=$2

while [ -z `mongosh --eval 'db.runCommand("ping").ok' --quiet --host $OPTS 2>/dev/null` ]; do
    echo "Waiting for MongoDB $NAME to start..."
    sleep 1
done

echo "MongoDB $NAME is up and running"

run.sh

run.sh will (1) start the replicants, (2) wait for the replicants to come up, and (3) define primary and secondary replicants on mongo1.

#!/bin/bash

set -e

# remove volumes
rm -rf .db

# drop existing containers
docker compose -f "docker-compose.yml" down

# prune containers
docker system prune --force

docker-compose -f "docker-compose.yml" up -d \
    --remove-orphans \
    --force-recreate \
    --build mongo1

docker-compose -f "docker-compose.yml" up -d \
    --remove-orphans \
    --force-recreate \
    --build mongo2

docker-compose -f "docker-compose.yml" up -d \
    --remove-orphans \
    --force-recreate \
    --build mongo3

docker-compose -f "docker-compose.yml" exec -T mongo3 /scripts/wait-for-mongodb.sh "mongo3:27017"
docker-compose -f "docker-compose.yml" exec -T mongo2 /scripts/wait-for-mongodb.sh "mongo2:27017"

M1_OPTS="--tls --tlsCAFile /data/ssl/ca.pem --tlsCertificateKeyFile /data/ssl/server.pem --tlsAllowInvalidCertificates"
docker-compose -f "docker-compose.yml" exec -T mongo1 /scripts/wait-for-mongodb.sh "mongo1:27017" "$M1_OPTS"

echo "Creating replica set..."
docker-compose -f "docker-compose.yml" exec -T mongo1 /scripts/init.sh

Putting everything together, we run the above shell script and then test our setup by opening a mongo shell:

mongosh --tls --tlsCAFile <path-to-ca-file> --tlsCertificateKeyFile <path-to-client-file>