Consolidate Mango integration tests

This commit groups a couple of major changes that aim to amend
many pain points in making the Mango integration test suites
more accessible.

- The test framework behind the Mango integration test suite
  provides a lot of flags that are not currently exposed on
  the level of the main `Makefile`.  Change this for the
  greater flexilibility.

- Mango's test suite documentation is buried in the source tree,
  which is not common for other kind of tests.  To increase its
  visibility and unify the style, move the contents of this file
  over to the general developer documentation.

- Promote the use of the `mango-test` target instead of setting
  up the related machinery manually.  The commands recorded in
  the original documentation are out of date and only minor
  implementation details anyway.

- Retire the explicit control over the activation of Mango
  integration tests that require support for text indexes.
  Instead learn the availability of this feature from the current
  CouchDB instance and run tests based on that.  This effectively
  makes the activation automated, which could be controlled
  implicitly by either hooking up of a Clouseau instance or not.

- Running the Mango integration tests do not remove the databases
  on their completion, which can inadvertently pollute the local
  data store.  To avoid this, enforce removal of test databases but
  allow it to be disabled on demand.

5 files changed, 57 insertions, 54 deletions

diff --git a/Makefile b/Makefile
index f44075d86..726d38d86 100644
--- a/Makefile
+++ b/Makefile
@@ -328,7 +328,11 @@ mango-test: devclean all
 	@cd src/mango && \
 		python3 -m venv .venv && \
 		.venv/bin/python3 -m pip install -r requirements.txt
-	@cd src/mango && ../../dev/run "$(TEST_OPTS)" -n 1 --admin=testuser:testpass '.venv/bin/python3 -m nose2'
+	@cd src/mango && \
+		../../dev/run "$(TEST_OPTS)" \
+		-n 1 \
+		--admin=adm:pass \
+		'COUCH_USER=adm COUCH_PASS=pass .venv/bin/python3 -m nose2 $(MANGO_TEST_OPTS)'
 
 
 .PHONY: weatherreport-test
diff --git a/Makefile.win b/Makefile.win
index c13528bba..458b61d47 100644
--- a/Makefile.win
+++ b/Makefile.win
@@ -294,7 +294,11 @@ mango-test: devclean all
 	@cd src\mango && \
 		python.exe -m venv .venv && \
 		.venv\Scripts\pip.exe install -r requirements.txt
-	@cd src\mango && .venv\Scripts\python.exe ..\..\dev\run -n 1 --admin=testuser:testpass .venv\Scripts\nose2
+	@cd src\mango && \
+		..\..\dev\run $(TEST_OPTS) \
+		-n 1 \
+		--admin=adm:pass \
+		"env COUCH_USER=adm COUCH_PASS=pass .venv\Scripts\nose2 $(MANGO_TEST_OPTS)"
 
 
 ################################################################################
diff --git a/README-DEV.rst b/README-DEV.rst
index d8fd299d8..dd527337a 100644
--- a/README-DEV.rst
+++ b/README-DEV.rst
@@ -239,6 +239,32 @@ Scala, and Maven) have been installed successfully, e.g.::
     git clone https://github.com/cloudant-labs/clouseau
     mvn -f clouseau/pom.xml scala:run
 
+Mango Integration Tests
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Tests for the Mango interface can be run individually with the help of
+the ``mango-test`` target and they can be narrowed down to specific
+test suites via the ``MANGO_TEST_OPTS`` variable::
+
+    make mango-test \
+      MANGO_TEST_OPTS="--pretty-assert --verbose 03-operator-test"
+
+The value of the ``MANGO_TEST_OPTS`` variable will be passed down to
+the `Nose 2 <https://nose2.io/>`_ testing framework which is used for
+the implementation.  Consult its documentation for more information.
+
+Tests that rely on text indexes are run only if the ``search`` feature
+is reported to be available (i.e. a working Clouseau instance is
+connected), otherwise they will be skipped.
+
+Note that the databases that are created during the tests will be all
+removed after each of the suites completed.  However, with the help of
+the ``MANGO_TESTS_KEEP_DBS`` environment variable, it can be requested
+to keep those databases around for further investigation::
+
+    MANGO_TESTS_KEEP_DBS=please \
+      make mango-test MANGO_TEST_OPTS='03-operator-test'
+
 Static Code Analysis
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/src/mango/test/README.md b/src/mango/test/README.md
deleted file mode 100644
index c2f8aada2..000000000
--- a/src/mango/test/README.md
+++ /dev/null
@@ -1,29 +0,0 @@
-Mango Tests
-===========
-
-CouchDB should be started with `./dev/run -a testuser:testpass`.
-
-To run these, do this in the Mango top level directory:
-
-    $ python3 -m venv venv
-    $ . venv/bin/activate
-    $ pip3 install -r requirements.txt
-    $ venv/bin/nose2
-
-To run an individual test suite:
-    nose2 12-use-correct-index-test
-
-To run the tests with text index support:
-    MANGO_TEXT_INDEXES=1 nose2 test
-
-
-Test configuration
-==================
-
-The following environment variables can be used to configure the test fixtures:
-
- * `COUCH_HOST` - root url (including port) of the CouchDB instance to run the tests against. Default is `"http://127.0.0.1:15984"`.
- * `COUCH_USER` - CouchDB username (with admin premissions). Default is `"testuser"`.
- * `COUCH_PASSWORD` -  CouchDB password. Default is `"testpass"`.
- * `COUCH_AUTH_HEADER` - Optional Authorization header value. If specified, this is used instead of basic authentication with the username/password variables above.
- * `MANGO_TEXT_INDEXES` - Set to `"1"` to run the tests only applicable to text indexes.
diff --git a/src/mango/test/mango.py b/src/mango/test/mango.py
index 03cb85f48..81bc082b6 100644
--- a/src/mango/test/mango.py
+++ b/src/mango/test/mango.py
@@ -23,17 +23,22 @@ import user_docs
 import limit_docs
 
 
+COUCH_HOST = "http://127.0.0.1:15984"
+COUCH_USER = os.environ.get("COUCH_USER")
+COUCH_PASS = os.environ.get("COUCH_PASS")
+
+
 def random_db_name():
     return "mango_test_" + uuid.uuid4().hex
 
 
 def has_text_service():
-    return os.environ.get("MANGO_TEXT_INDEXES") == "1"
+    features = requests.get(COUCH_HOST).json()["features"]
+    return "search" in features
 
 
-def get_from_environment(key, default):
-    value = os.environ.get(key)
-    return value if value is not None else default
+def clean_up_dbs():
+    return not os.environ.get("MANGO_TESTS_KEEP_DBS")
 
 
 # add delay functionality
@@ -46,32 +51,15 @@ class Database(object):
     def __init__(
         self,
         dbname,
-        host="127.0.0.1",
-        port="15984",
-        user="testuser",
-        password="testpass",
     ):
-        root_url = get_from_environment("COUCH_HOST", "http://{}:{}".format(host, port))
-        auth_header = get_from_environment("COUCH_AUTH_HEADER", None)
-        user = get_from_environment("COUCH_USER", user)
-        password = get_from_environment("COUCH_PASSWORD", password)
-
-        self.root_url = root_url
         self.dbname = dbname
         self.sess = requests.session()
-
-        # allow explicit auth header to be set to enable testing
-        # against deployments where basic auth isn't available
-        if auth_header is not None:
-            self.sess.headers["Authorization"] = auth_header
-        else:
-            self.sess.auth = (user, password)
-
+        self.sess.auth = (COUCH_USER, COUCH_PASS)
         self.sess.headers["Content-Type"] = "application/json"
 
     @property
     def url(self):
-        return "{}/{}".format(self.root_url, self.dbname)
+        return "{}/{}".format(COUCH_HOST, self.dbname)
 
     def path(self, parts):
         if isinstance(parts, ("".__class__, "".__class__)):
@@ -299,6 +287,11 @@ class UsersDbTests(unittest.TestCase):
         klass.db = Database("_users")
         user_docs.setup_users(klass.db)
 
+    @classmethod
+    def tearDownClass(klass):
+        if clean_up_dbs():
+            klass.db.delete()
+
     def setUp(self):
         self.db = self.__class__.db
 
@@ -309,6 +302,11 @@ class DbPerClass(unittest.TestCase):
         klass.db = Database(random_db_name())
         klass.db.create(q=1, n=1)
 
+    @classmethod
+    def tearDownClass(klass):
+        if clean_up_dbs():
+            klass.db.delete()
+
     def setUp(self):
         self.db = self.__class__.db