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.

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

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)"
 
 
 ################################################################################

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
 ~~~~~~~~~~~~~~~~~~~~
 

src/mango/test/mango.py

@@ -23,17 +23,22 @@
 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 @@ def setUpClass(klass):
         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 @@ def setUpClass(klass):
         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