coverage commands so we can see coverage across all Pythons

Makefile

@@ -55,6 +55,12 @@ test_twisted_coverage:
 	coverage html
 	coverage report --show-missing
 
+test_coverage:
+	-rm .coverage
+	tox -e py27twisted,py27asyncio,py34asyncio
+	coverage html
+	coverage report --show-missing
+
 # test under asyncio
 test_asyncio:
 	USE_ASYNCIO=1 python -m pytest -rsx

doc/contribute.rst

@@ -17,3 +17,13 @@ This means that you fork the repo, make changes to your fork, and then make a pu
 This `article on GitHub <https://help.github.com/articles/using-pull-requests>`_ gives more detailed information on how the process works.
 
 
+Running the Tests
+-----------------
+
+In order to run the unit-tests, we use `Tox <http://tox.readthedocs.org/en/latest/>`_ to build the various test-environments. To run them all, simply run ``tox`` from the top-level directory of the clone.
+
+For test-coverage, see the Makefile target ``test_coverage``, which deletes the coverage data and then runs the test suite with various tox test-environments before outputting HTML annotated coverage to ``./htmlcov/index.html`` and a coverage report to the terminal.
+
+There are two environment variables the tests use: ``USE_TWISTED=1`` or ``USE_ASYNCIO=1`` control whether to run unit-tests that are specific to one framework or the other.
+
+See ``tox.ini`` for details on how to run in the different environments

tox.ini

@@ -69,9 +69,9 @@ commands =
    coverage --version
    {envbindir}/trial --version
    # XXX should probably add --branch
-   coverage run --source=autobahn --omit=*test* {envbindir}/trial autobahn
+   # note: always doing --append so we can get coverage across all
-   coverage report --show-missing
+   # Python versions at once; see "make test_coverage"
-   coverage html
+   coverage run --append --source=autobahn --omit=*test* {envbindir}/trial autobahn
 basepython = python2.7
 install_command = pip install {packages} autobahn[twisted,serialization]
 setenv =
@@ -82,7 +82,8 @@ setenv =
 commands =
    sh -c "which python"
    python -V
-   py.test autobahn/
+   coverage --version
+   coverage run --append --source=autobahn --omit=*test* {envbindir}/py.test autobahn/
 basepython = python2.7
 install_command = pip install {packages} autobahn[asyncio,serialization]
 setenv =
@@ -93,7 +94,8 @@ setenv =
 commands =
    sh -c "which python"
    python -V
-   py.test autobahn/
+   coverage --version
+   coverage run --append --source=autobahn --omit=*test* {envbindir}/py.test autobahn/
 basepython = python3.3
 install_command = pip install {packages} autobahn[asyncio,serialization]
 setenv =
@@ -104,7 +106,8 @@ setenv =
 commands =
    sh -c "which python"
    python -V
-   py.test autobahn/
+   coverage --version
+   coverage run --append --source=autobahn --omit=*test* {envbindir}/py.test autobahn/
 basepython = python3.4
 install_command = pip install {packages} autobahn[asyncio,serialization]
 setenv =
@@ -118,9 +121,11 @@ deps =
 commands =
    sh -c "which python"
    sh -c "which trial"
+   sh -c "which coverage"
    python -V
-   trial --version
+   {envbindir}/trial --version
-   trial autobahn
+   coverage --version
+   coverage run --append --source=autobahn --omit=*test* {envbindir}/trial autobahn/
 basepython = pypy
 install_command = pip install {packages} autobahn[twisted,serialization]
 setenv =
@@ -130,8 +135,11 @@ setenv =
 [testenv:pypy2asyncio]
 commands =
    sh -c "which python"
+   sh -c "which coverage"
    python -V
-   py.test autobahn/
+   coverage --version
+   {envbindir}/py.test --version
+   coverage run --append --source=autobahn --omit=*test* {envbindir}/py.test autobahn/
 basepython = pypy
 install_command = pip install {packages} autobahn[asyncio,serialization]
 setenv =