From 8851b71c6f47f3d4b4c723118d9600e56421dad7 Mon Sep 17 00:00:00 2001 From: Michael Foord Date: Sat, 8 May 2010 15:09:37 +0000 Subject: Documenting test discovery from package name and potential problems with test discovery importing tests from the wrong location. Issue 7780 and issue 8547. --- Doc/library/unittest.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index f28e73f..f3bd780 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -280,6 +280,27 @@ 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`_. -- cgit v0.12