Rev 2521: Doc testing of exceptions in http://sourcefrog.net/bzr/doc

[Martin Pool]

At http://sourcefrog.net/bzr/doc

------------------------------------------------------------
revno: 2521
revision-id: 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:
  doc/configuration.txt          configuration.txt-20060314161707-868350809502af01
  doc/developers/HACKING         HACKING-20050805200004-2a5dc975d870f78c
=== modified file 'doc/configuration.txt'
--- a/doc/configuration.txt	2007-04-23 01:30:35 +0000
+++ b/doc/configuration.txt	2007-07-12 09:11:15 +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-05-30 12:45:23 +0000
+++ b/doc/developers/HACKING	2007-07-12 09:11:15 +0000
@@ -372,6 +372,34 @@
 fix for it, or if something works on Unix but not on Windows.
 
 
+Testing Bazaar
+--------------
+
+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(?)
+
 
 Essential Domain Classes
 ########################