Improve documentation and make commands for tests

Previously the readme said that tests could be run with `make`.
This was not the case as a TOPOLOGY variable had to be set. This
patch adds a check to ensure that variables used in testing are
set to valid values. It also outlines usage of testing variables
in the readme.

Change-Id: I7f60fb78282f08ca528f64e40b87fed67b5780f7

Author: tfogo

Makefile

@@ -14,7 +14,11 @@ TEST_PKGS = $(BSON_TEST_PKGS) $(MONGO_TEST_PKGS) $(UNSTABLE_TEST_PKGS) $(TAG_PKG
 TEST_TIMEOUT = 600
 
 .PHONY: default
-default: check-fmt vet build-examples lint errcheck test-cover test-race
+default: check-env check-fmt vet build-examples lint errcheck test-cover test-race
+
+.PHONY: check-env
+check-env:
+	etc/check_env.sh
 
 .PHONY: doc
 doc:

README.md

@@ -124,8 +124,63 @@ New Features and bugs can be reported on jira: https://jira.mongodb.org/browse/G
 -------------------------
 ## Testing / Development
 
-To run driver tests, make sure a MongoDB server instance is running at localhost:27017. Using make, you can run `make` (on windows, run `nmake`).
-This will run coverage, run go-lint, run go-vet, and build the examples.
+The driver tests can be run against several database configurations. The most simple configuration is a standalone mongod with no auth, no ssl, and no compression. To run these basic driver tests, make sure a standalone MongoDB server instance is running at localhost:27017. To run the tests, you can run `make` (on Windows, run `nmake`) with the following:
+
+```
+TOPOLOGY=server make
+```
+
+The `TOPOLOGY`variable must be set to run tests. This will run coverage, run go-lint, run go-vet, and build the examples.
+
+### Testing Different Topologies
+
+To test a **replica set**, set `MONGODB_URI="<connection-string>"` and `TOPOLOGY=replica_set` for the `make` command. For example, for a local replica set named `rs1` comprised of three nodes on ports 27017, 27018, and 27019:
+
+```
+MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27018/?replicaSet=rs1" TOPOLOGY=replica_set make
+```
+
+To test a **sharded cluster**, set `MONGODB_URI="<connection-string>"` and `TOPOLOGY=sharded_cluster` variables for the `make` command. For example, for a sharded cluster with a single mongos on port 27017:
+
+```
+MONGODB_URI="mongodb://localhost:27017/" TOPOLOGY=sharder_cluster make
+```
+
+### Testing Auth and SSL
+
+To test authentication and SSL, first set up a MongoDB cluster with auth and SSL configured. Testing authentication requires a user with the `root` role on the `admin` database. The Go Driver repository comes with example certificates in the `data/certificates` directory. These certs can be used for testing. Here is an example command that would run a mongod with SSL correctly configured for tests:
+
+```
+mongod \
+--auth \
+--sslMode requireSSL \
+--sslPEMKeyFile $(pwd)/data/certificates/server.pem \
+--sslCAFile $(pwd)/data/certificates/ca.pem \
+--sslWeakCertificateValidation
+```
+
+To run the tests with `make`, set `MONGO_GO_DRIVER_CA_FILE` to the location of the CA file used by the database, set `MONGODB_URI` to the connection string of the server, set `AUTH=auth`, and set `SSL=ssl`. For example:
+
+```
+AUTH=auth SSL=ssl MONGO_GO_DRIVER_CA_FILE=$(pwd)/data/certificates/ca.pem  MONGODB_URI="mongodb://user:password@localhost:27017/?authSource=admin" make
+```
+
+Notes:
+- The `--sslWeakCertificateValidation` flag is required on the server for the test suite to work correctly.
+- The test suite requires the auth database to be set with `?authSource=admin`, not `/admin`.
+
+### Testing Compression
+
+The MongoDB Go Driver supports wire protocol compression using Snappy or zLib. To run tests with wire protocol compression, set `MONGO_GO_DRIVER_COMPRESSOR` to `snappy` or `zlib`.  For example:
+
+```
+MONGO_GO_DRIVER_COMPRESSOR=snappy make
+```
+
+Ensure the [`--networkMessageCompressors` flag](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-networkmessagecompressors) on mongod or mongos includes `zlib` if testing zLib compression.
+
+-------------------------
+## Feedback
 
 The MongoDB Go Driver is not feature complete, so any help is appreciated. Check out the [project page](https://jira.mongodb.org/browse/GODRIVER)
 for tickets that need completing. See our [contribution guidelines](CONTRIBUTING.md) for details.

etc/check_env.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+if [[ ! $TOPOLOGY =~ ^(server|replica_set|sharded_cluster)$ ]]; then
+    >&2 echo "Invalid value of TOPOLOGY. TOPOLOGY must be set to one of: server, replica_set, sharded_cluster"
+    exit 1
+fi
+
+if [ ! -z $AUTH ] && [[ ! $AUTH =~ ^(noauth|auth)$ ]]; then
+    >&2 echo "Invalid value of AUTH. AUTH can optionally be set to one of: noauth, auth"
+    exit 1
+fi
+
+if [ ! -z $SSL ] && [[ ! $SLL =~ ^(nossl|ssl)$ ]]; then
+    >&2 echo "Invalid value of SSL. SSL can optionally be set to one of: nossl, ssl"
+    exit 1
+fi
+
+if [ ! -z $MONGO_GO_DRIVER_COMPRESSOR ] && [[ ! $MONGO_GO_DRIVER_COMPRESSOR =~ ^(snappy|zlib)$ ]]; then
+    >&2 echo "Invalid value of MONGO_GO_DRIVER_COMPRESSOR. MONGO_GO_DRIVER_COMPRESSOR can optionally be set to one of: snappy, zlib"
+    exit 1
+fi