Categorygithub.com/mongo-go/testdb
modulepackage
0.0.0-20201209140737-c4845cc6fe67
Repository: https://github.com/mongo-go/testdb.git
Documentation: pkg.go.dev

# README

Test databases for MongoDB, made easy.

Build Status Go Report Card Coverage Status GoDoc

This is a small Go package that makes it easy to create databases/collections for MongoDB tests. It's useful when you want to run tests against an actual MongoDB instance.

Setup

Install the package with "go get".

go get "github.com/mongo-go/testdb"

This package should only be imported in tests; you should never use it in actual code.

Usage

Here is an example of how to use this package:

package main_test

import (
        "testing"

        "github.com/mongo-go/testdb"
)

var testDb *testdb.TestDB

func setup(t *testing.T) *mgo.Collection {
	if testDb == nil {
		testDb = testdb.NewTestDB("mongodb://localhost", "your_db", time.Duration(2) * time.Second)

		err := testDb.Connect()
		if err != nil {
			t.Fatal(err)
		}
        }

        coll, err := testDb.CreateRandomCollection(testdb.NoIndexes)
        if err != nil {
                t.Fatal(err)
        }

        return coll // random *mongo.Collection in "your_db"
}

func Test1(t *testing.T) {
        coll := setup(t)
	defer coll.Drop(context.Background())

        // Test queries using coll
}

Overriding Defaults with Environement Variables

One of the benefits of using this package is that it allows you to override certain defaults with environment variables. These are the env vars currently supported:

  • TEST_MONGO_URL: overrides the url of the MongoDB instance being used for testing.
  • TEST_MONGO_DB: overrides the database name being used for testing.

By default, even if these env vars are set, they will not be used. To use them, you must call the OverrideWithEnvVars on a TestDB before calling Connect, like so:

// export TEST_MONGO_URL="their_url"
// export TEST_MONGO_DB="their_db"

testDb := testdb.NewTestDB("mongodb://localhost", "your_db", time.Duration(2) * time.Second)
testDb.OverrideWithEnvVars()

err := testdb.Conect() {
        // ...
}

Why is this useful? Say you have some tests that connect to MongoDB, which you always have running locally at "mongodb://localhost". Hardcoding your tests to create a TestDB with that url works fine for you, but what about when someone else who has MongoDB running locally at "their_url" tries to run your tests? By calling OverrideWithEnvVars in your tests you give whoever is invoking them the ability to change the url and database of the TestDB without having to change any code.

Tests

Tests for this package require an instance of MongoDB to be running at "localhost" (no port). They write into the db "test" and collection "testdb_collection", and delete all documents from that collection after they run.

Run the tests from the root directory of this repo like so:

go test `go list ./... | grep -v "/vendor/"` --race

# Functions

IsDupeKeyError returns true if the error is a Mongo duplicate key error.
NewTestDB creates a new TestDB with the provided url, database name, and timeout.

# Constants

ENV_VAR_TEST_MONGO_DB is an environment variable that, if set, can override the MongoDB database used in a TestDB.
ENV_VAR_TEST_MONGO_URL is an environment variable that, if set, can override the MongoDB url used in a TestDB.

# Variables

NoIndexes can be passed to CreateRandomCollection to create a collection without indexes.

# Structs

A TestDB represents a MongoDB database used for running tests against.