unittest2, discover and tox

Running unittests with ‘discover’

The discover project allows you to discover and run unittests that you can easily integrate it in a tox run. As an example, perform a checkout of Pygments:

hg clone https://bitbucket.org/birkenfeld/pygments-main

and add the following tox.ini to it:

[tox]
envlist = py27,py35,py36

[testenv]
changedir = tests
commands = discover
deps = discover

If you now invoke tox you will see the creation of three virtual environments and a unittest-run performed in each of them.

Running unittest2 and sphinx tests in one go

Michael Foord has contributed a tox.ini file that allows you to run all tests for his mock project, including some sphinx-based doctests. If you checkout its repository with:

git clone https://github.com/testing-cabal/mock.git

The checkout has a tox.ini file that looks like this:

[tox]
envlist = py27,py35,py36,py37

[testenv]
deps = unittest2
commands = unit2 discover []

[testenv:py36]
commands =
    unit2 discover []
    sphinx-build -b doctest docs html
    sphinx-build docs html
deps =
    unittest2
    sphinx

[testenv:py27]
commands =
    unit2 discover []
    sphinx-build -b doctest docs html
    sphinx-build docs html
deps =
    unittest2
    sphinx

mock uses unittest2 to run the tests. Invoking tox starts test discovery by executing the unit2 discover commands on Python 2.7, 3.5, 3.6 and 3.7 respectively. Against Python3.6 and Python2.7 it will additionally run sphinx-mediated doctests. If building the docs fails, due to a reST error, or any of the doctests fails, it will be reported by the tox run.

The [] parentheses in the commands provide Interactive shell substitution which means you can e.g. type:

tox -- -f -s SOMEPATH

which will ultimately invoke:

unit2 discover -f -s SOMEPATH

in each of the environments. This allows you to customize test discovery in your tox runs.