# 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.