[Python-checkins] merge in devguide (hg_transition): Merged from default

[brett.cannon]

brett.cannon pushed c500a1efc984 to devguide:

http://hg.python.org/devguide/rev/c500a1efc984
changeset:   338:c500a1efc984
branch:      hg_transition
tag:         tip
parent:      334:140b84af4344
parent:      337:7ce1bf0f6f5d
user:        Brett Cannon <brett at python.org>
date:        Sat Feb 26 22:31:17 2011 -0800
summary:
  Merged from default

files:
  

diff --git a/coverage.rst b/coverage.rst
--- a/coverage.rst
+++ b/coverage.rst
@@ -33,9 +33,8 @@
 
 Finally, you can simply run the entire test suite yourself with coverage turned
 on and see what modules need help. This has the drawback of running the entire
-test suite under coverage measuring which
-takes some time to complete, but you will
-have an accurate, up-to-date notion of what modules need the most work.
+test suite under coverage measuring which takes some time to complete, but you
+will have an accurate, up-to-date notion of what modules need the most work.
 
 Do make sure, though, that for any module you do decide to work on that you run
 coverage for just that module. This will make sure you know how good the
@@ -43,6 +42,24 @@
 implicit testing by other code that happens to use the module.
 
 
+Common Gotchas
+""""""""""""""
+
+Please realize that coverage reports on modules already imported before coverage
+data starts to be recorded will be wrong. Typically you can tell a module falls
+into this category by the coverage report saying that global statements that
+would obviously be executed upon import have gone unexecuted while local
+statements have been covered. In these instances you can ignore the global
+statement coverage and simply focus on the local statement coverage.
+
+When writing new tests to increase coverage, do take note of the style of tests
+already provided for a module (e.g., whitebox, blackbox, etc.). As
+some modules are primarily maintained by a single core developer they may have
+a specific preference as to what kind of test is used (e.g., whitebox) and
+prefer that other types of tests not be used (e.g., blackbox). When in doubt,
+stick with whitebox testing in order to properly exercise the code.
+
+
 Measuring Coverage
 """"""""""""""""""
 
@@ -130,7 +147,7 @@
 goal to strive for, is a secondary goal to getting 100% line
 coverage for the entire stdlib (for now).
 
-If you decide to want to try to improve branch coverage, simply add the
+If you decide you want to try to improve branch coverage, simply add the
 ``--branch`` flag to your coverage run::
 
     ./python -m coverage run --pylib --branch <arguments to run test(s)>

--
Repository URL: http://hg.python.org/devguide