Rev 2608: (mbp, r=robert) doc testing of exceptions in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 2608
revision-id: pqm at pqm.ubuntu.com-20070712114408-7iozx4b8hq8ts24n
parent: pqm at pqm.ubuntu.com-20070712104858-axdt2sml59kw4fjg
parent: mbp at sourcefrog.net-20070712094950-tvvsyf0rf2d2m86d
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-07-12 12:44:08 +0100
message:
  (mbp,r=robert) doc testing of exceptions
modified:
  doc/configuration.txt          configuration.txt-20060314161707-868350809502af01
  doc/developers/HACKING         HACKING-20050805200004-2a5dc975d870f78c
    ------------------------------------------------------------
    revno: 2513.1.9
    merged: mbp at sourcefrog.net-20070712094950-tvvsyf0rf2d2m86d
    parent: mbp at sourcefrog.net-20070712091115-uhg5zz3blan43m85
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc
    timestamp: Thu 2007-07-12 19:49:50 +1000
    message:
      Exception testing review comments
    ------------------------------------------------------------
    revno: 2513.1.8
    merged: mbp at sourcefrog.net-20070712091115-uhg5zz3blan43m85
    parent: mbp at sourcefrog.net-20070626041504-sxdk4kjal60vnbxl
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc
    timestamp: Thu 2007-07-12 19:11:15 +1000
    message:
      Doc testing of exceptions
=== modified file 'doc/configuration.txt'
--- a/doc/configuration.txt	2007-06-19 16:11:26 +0000
+++ b/doc/configuration.txt	2007-07-12 11:44:08 +0000
@@ -4,6 +4,10 @@
 
 Information on how to configure Bazaar.
 
+
+.. TODO: Should have some explanation of why you'd want things in
+.. branch.conf.
+
 Location of configuration file
 ==============================
 Each user gets a pair of configurations files in ``$HOME/.bazaar``. The first

=== modified file 'doc/developers/HACKING'
--- a/doc/developers/HACKING	2007-07-12 07:39:44 +0000
+++ b/doc/developers/HACKING	2007-07-12 11:44:08 +0000
@@ -372,6 +372,37 @@
 fix for it, or if something works on Unix but not on Windows.
 
 
+Testing exceptions and errors
+-----------------------------
+
+It's important to test handling of errors and exceptions.  Because this
+code is often not hit in ad-hoc testing it can often have hidden bugs --
+it's particularly common to get NameError because the exception code
+references a variable that has since been renamed.
+
+.. TODO: Something about how to provoke errors in the right way?
+
+In general we want to test errors at two levels:
+
+1. A test in ``test_errors.py`` checking that when the exception object is
+   constructed with known parameters it produces an expected string form.
+   This guards against mistakes in writing the format string, or in the
+   ``str`` representations of its parameters.  There should be one for
+   each exception class.
+
+2. Tests that when an api is called in a particular situation, it raises
+   an error of the expected class.  You should typically use
+   ``assertRaises``, which in the Bazaar test suite returns the exception
+   object to allow you to examine its parameters.  
+
+In some cases blackbox tests will also want to check error reporting.  But
+it can be difficult to provoke every error through the commandline
+interface, so those tests are only done as needed -- eg in response to a
+particular bug or if the error is reported in an unusual way(?)  Blackbox
+tests should mostly be testing how the command-line interface works, so
+should only test errors if there is something particular to the cli in how
+they're displayed or handled.
+
 
 Essential Domain Classes
 ########################