Merged revisions 80980 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r80980 | michael.foord | 2010-05-08 17:09:37 +0200 (Sat, 08 May 2010) | 1 line

  Documenting test discovery from package name and potential problems with test discovery importing tests from the wrong location. Issue 7780 and issue 8547.
........

1 files changed, 21 insertions, 0 deletions

diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 7dc8595..b5b23c7 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -276,6 +276,27 @@ following two command lines are equivalent::
    python -m unittest discover -s project_directory -p '*_test.py'
    python -m unittest discover project_directory '*_test.py'
 
+As well as being a path it is possible to pass a package name, for example
+``myproject.subpackage.test``, as the start directory. The package name you
+supply will then be imported and its location on the filesystem will be used
+as the start directory.
+
+.. caution::
+
+    Test discovery loads tests by importing them. Once test discovery has
+    found all the test files from the start directory you specify it turns the
+    paths into package names to import. For example `foo/bar/baz.py` will be
+    imported as ``foo.bar.baz``.
+
+    If you have a package installed globally and attempt test discovery on
+    a different copy of the package then the import *could* happen from the
+    wrong place. If this happens test discovery will warn you and exit.
+
+    If you supply the start directory as a package name rather than a
+    path to a directory then discover assumes that whichever location it
+    imports from is the location you intended, so you will not get the
+    warning.
+
 Test modules and packages can customize test loading and discovery by through
 the `load_tests protocol`_.