documentation on setup test_suite argument

Question

Feature in question

I'm looking for documentation on a feature that let's you specify the test cases for a python packages and run them using setup. For example if my setup.py file was:

from setuptools setup
setup(
    name='foo',
    version='1.0',
    py_modules=['foo'],
    test_suite='testsuite.test_all.suite',
)

I could then run the package's test cases with the following command:

python setup.py test

Where I have looked

• The PEP Index - there are many PEPs related to packaging I couldn't find mention of the test_suite feature in them.
• Distributing Python Modules documentation mention it either.

What I want to know

• what does test_suite expect? from what I can tell it expects a test suite and you can refer to one directly or a callable that returns one.
• Some projects specify their test suite in their setup.py like Flask some don't like Django. What is the benefit of specifying this.

Answer 1

The documentation for distribute has a very good section called Build package and run a unittest suite that explains the use of test_suite pretty well.

what does test_suite expect?

To use this command, your project’s tests must be wrapped in a unittest test suite by either a function, a TestCase class or method, or a module or package containing TestCase classes. If the named suite is a module, and the module has an additional_tests() function, it is called and the result (which must be a unittest.TestSuite) is added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite.

What is the benefit of specifying this?

By specifying the testing mechanism in your setup.py applications can automatically detect where the test suites are and run them.