[Python-checkins] devguide: List common gotchas people might come across when doing coverage work.

[brett.cannon]

brett.cannon pushed 00260cf660c8 to devguide:

http://hg.python.org/devguide/rev/00260cf660c8
changeset:   336:00260cf660c8
user:        Brett Cannon <brett at python.org>
date:        Sat Feb 26 22:30:48 2011 -0800
summary:
  List common gotchas people might come across when doing coverage work.
Currently this includes coverage for modules which are already
imported (i.e., bootstrap-required modules) and matching the
pre-existing testing style for a module and leaning towards whitebox
testing when in doubt.

files:
  coverage.rst

diff --git a/coverage.rst b/coverage.rst
--- a/coverage.rst
+++ b/coverage.rst
@@ -42,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
 """"""""""""""""""
 

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