Rev 2490: (Robert Collins) Document TreeBuilder, and do some cleanup. in http://bzr.arbash-meinel.com/branches/bzr/jam-integration
John Arbash Meinel
john at arbash-meinel.com
Wed May 23 10:07:48 BST 2007
At http://bzr.arbash-meinel.com/branches/bzr/jam-integration
------------------------------------------------------------
revno: 2490
revision-id: john at arbash-meinel.com-20070523090735-3uf48sdb33qh79g4
parent: john at arbash-meinel.com-20070523085414-8o53d2txzpn4ni9y
parent: robertc at robertcollins.net-20070427003620-6fjf8dbiblgt5am7
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: jam-integration
timestamp: Wed 2007-05-23 04:07:35 -0500
message:
(Robert Collins) Document TreeBuilder, and do some cleanup.
modified:
bzrlib/tests/test_treebuilder.py test_treebuilder.py-20060907214856-4omn6hf1u7fvrart-2
doc/developers/HACKING HACKING-20050805200004-2a5dc975d870f78c
------------------------------------------------------------
revno: 2466.7.2
merged: robertc at robertcollins.net-20070427003620-6fjf8dbiblgt5am7
parent: robertc at robertcollins.net-20070427001815-3m1u2fk695um4oyb
committer: Robert Collins <robertc at robertcollins.net>
branch nick: build-branch
timestamp: Fri 2007-04-27 10:36:20 +1000
message:
Document the user of TreeBuilder somewhat.
------------------------------------------------------------
revno: 2466.7.1
merged: robertc at robertcollins.net-20070427001815-3m1u2fk695um4oyb
parent: pqm at pqm.ubuntu.com-20070426211103-h84prqh7a4ad3ez2
committer: Robert Collins <robertc at robertcollins.net>
branch nick: build-branch
timestamp: Fri 2007-04-27 10:18:15 +1000
message:
Tree builder tests do not need a working dir.
-------------- next part --------------
=== modified file 'bzrlib/tests/test_treebuilder.py'
--- a/bzrlib/tests/test_treebuilder.py 2006-09-15 22:46:02 +0000
+++ b/bzrlib/tests/test_treebuilder.py 2007-04-27 00:18:15 +0000
@@ -17,7 +17,7 @@
"""Tests for the TreeBuilder helper class."""
-from bzrlib import errors
+from bzrlib import errors, tests
from bzrlib.memorytree import MemoryTree
from bzrlib.tests import TestCaseWithTransport
from bzrlib.treebuilder import TreeBuilder
@@ -48,7 +48,7 @@
self.assertEqual(["lock_tree_write", "unlock"], tree._calls)
-class TestTreeBuilder(TestCaseWithTransport):
+class TestTreeBuilderMemoryTree(tests.TestCaseWithMemoryTransport):
def test_create(self):
builder = TreeBuilder()
@@ -92,3 +92,4 @@
self.assertEqual('contents of bar/file\n',
tree.get_file(tree.path2id('bar/file')).read())
builder.finish_tree()
+
=== modified file 'doc/developers/HACKING'
--- a/doc/developers/HACKING 2007-05-07 16:48:14 +0000
+++ b/doc/developers/HACKING 2007-05-23 09:07:35 +0000
@@ -227,7 +227,7 @@
test before writing the code.
In general, you can test at either the command-line level or the
- internal API level. See Writing Tests below for more detail.
+ internal API level. See Writing tests below for more detail.
* Try to practice Test-Driven Development: before fixing a bug, write a
test case so that it does not regress. Similarly for adding a new
@@ -693,6 +693,105 @@
should be only in the command-line tool.
+Writing tests
+=============
+
+In general tests should be placed in a file named test_FOO.py where
+FOO is the logical thing under test. That file should be placed in the
+tests subdirectory under the package being tested.
+
+For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
+See bzrlib/tests/test_sampler.py for a template test script.
+
+Tests can be written for the UI or for individual areas of the library.
+Choose whichever is appropriate: if adding a new command, or a new command
+option, then you should be writing a UI test. If you are both adding UI
+functionality and library functionality, you will want to write tests for
+both the UI and the core behaviours. We call UI tests 'blackbox' tests
+and they are found in ``bzrlib/tests/blackbox/*.py``.
+
+When writing blackbox tests please honour the following conventions:
+
+ 1. Place the tests for the command 'name' in
+ bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
+ to locate the test script for a faulty command.
+
+ 2. Use the 'self.run_bzr("name")' utility function to invoke the command
+ rather than running bzr in a subprocess or invoking the
+ cmd_object.run() method directly. This is a lot faster than
+ subprocesses and generates the same logging output as running it in a
+ subprocess (which invoking the method directly does not).
+
+ 3. Only test the one command in a single test script. Use the bzrlib
+ library when setting up tests and when evaluating the side-effects of
+ the command. We do this so that the library api has continual pressure
+ on it to be as functional as the command line in a simple manner, and
+ to isolate knock-on effects throughout the blackbox test suite when a
+ command changes its name or signature. Ideally only the tests for a
+ given command are affected when a given command is changed.
+
+ 4. If you have a test which does actually require running bzr in a
+ subprocess you can use ``run_bzr_subprocess``. By default the spawned
+ process will not load plugins unless ``--allow-plugins`` is supplied.
+
+
+Test support
+------------
+
+We have a rich collection of tools to support writing tests. Please use
+them in preference to ad-hoc solutions as they provide portability and
+performance benefits.
+
+TreeBuilder
+~~~~~~~~~~~
+
+The ``TreeBuilder`` interface allows the construction of arbitrary trees
+with a declarative interface. A sample session might look like::
+
+ tree = self.make_branch_and_tree('path')
+ builder = TreeBuilder()
+ builder.start_tree(tree)
+ builder.build(['foo', "bar/", "bar/file"])
+ tree.commit('commit the tree')
+ builder.finish_tree()
+
+Please see bzrlib.treebuilder for more details.
+
+
+Doctests
+--------
+
+We make selective use of doctests__. In general they should provide
+*examples* within the API documentation which can incidentally be tested. We
+don't try to test every important case using doctests -- regular Python
+tests are generally a better solution.
+
+Most of these are in ``bzrlib/doc/api``. More additions are welcome.
+
+ __ http://docs.python.org/lib/module-doctest.html
+
+
+Running tests
+=============
+Currently, bzr selftest is used to invoke tests.
+You can provide a pattern argument to run a subset. For example,
+to run just the blackbox tests, run::
+
+ ./bzr selftest -v blackbox
+
+To skip a particular test (or set of tests), use the --exclude option
+(shorthand -x) like so::
+
+ ./bzr selftest -v -x blackbox
+
+To list tests without running them, use the --list-only option like so::
+
+ ./bzr selftest --list-only
+
+This option can be combined with other selftest options (like -x) and
+filter patterns to understand their effect.
+
+
Handling Errors and Exceptions
==============================
More information about the bazaar-commits
mailing list