Adds a verbosity keyword argument to unittest.main plus a minor fix allowing you to specify test modules / classes
from the command line.
Closes issue 5995.
Michael Foord
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index e1d416d..0af3ea3 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -91,6 +91,31 @@
`python-mock <http://python-mock.sourceforge.net/>`_ and `minimock <http://blog.ianbicking.org/minimock.html>`_
Tools for creating mock test objects (objects simulating external resources).
+Command Line Interface
+----------------------
+
+The unittest module can be used from the command line to run tests from
+modules, classes or even individual test methods::
+
+ python -m unittest test_module1 test_module2
+ python -m unittest test_module.TestClass
+ python -m unittest test_module.TestClass.test_method
+
+You can pass in a list with any combination of module names, and fully qualified class or
+method names.
+
+You can run tests with more detail (higher verbosity) by passing in the -v flag::
+
+ python-m unittest -v test_module
+
+For a list of all the command line options::
+
+ python -m unittest -h
+
+.. versionchanged:: 27
+ In earlier versions it was only possible to run individual test methods and not modules
+ or classes.
+
.. _unittest-minimal-example:
Basic example
@@ -178,7 +203,6 @@
are sufficient to meet many everyday testing needs. The remainder of the
documentation explores the full feature set from first principles.
-
.. _organizing-tests:
Organizing test code
@@ -1408,7 +1432,7 @@
subclasses to provide a custom ``TestResult``.
-.. function:: main([module[, defaultTest[, argv[, testRunner[, testLoader[, exit]]]]]])
+.. function:: main([module[, defaultTest[, argv[, testRunner[, testLoader[, exit, [verbosity]]]]]]])
A command-line program that runs a set of tests; this is primarily for making
test modules conveniently executable. The simplest use for this function is to
@@ -1417,6 +1441,12 @@
if __name__ == '__main__':
unittest.main()
+ You can run tests with more detailed information by passing in the verbosity
+ argument::
+
+ if __name__ == '__main__':
+ unittest.main(verbosity=2)
+
The *testRunner* argument can either be a test runner class or an already
created instance of it. By default ``main`` calls :func:`sys.exit` with
an exit code indicating success or failure of the tests run.
@@ -1432,4 +1462,4 @@
This stores the result of the tests run as the ``result`` attribute.
.. versionchanged:: 2.7
- The ``exit`` parameter was added.
+ The ``exit`` and ``verbosity`` parameters were added.