693
693
should be only in the command-line tool.
699
In general tests should be placed in a file named test_FOO.py where
700
FOO is the logical thing under test. That file should be placed in the
701
tests subdirectory under the package being tested.
703
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
704
See bzrlib/tests/test_sampler.py for a template test script.
706
Tests can be written for the UI or for individual areas of the library.
707
Choose whichever is appropriate: if adding a new command, or a new command
708
option, then you should be writing a UI test. If you are both adding UI
709
functionality and library functionality, you will want to write tests for
710
both the UI and the core behaviours. We call UI tests 'blackbox' tests
711
and they are found in ``bzrlib/tests/blackbox/*.py``.
713
When writing blackbox tests please honour the following conventions:
715
1. Place the tests for the command 'name' in
716
bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
717
to locate the test script for a faulty command.
719
2. Use the 'self.run_bzr("name")' utility function to invoke the command
720
rather than running bzr in a subprocess or invoking the
721
cmd_object.run() method directly. This is a lot faster than
722
subprocesses and generates the same logging output as running it in a
723
subprocess (which invoking the method directly does not).
725
3. Only test the one command in a single test script. Use the bzrlib
726
library when setting up tests and when evaluating the side-effects of
727
the command. We do this so that the library api has continual pressure
728
on it to be as functional as the command line in a simple manner, and
729
to isolate knock-on effects throughout the blackbox test suite when a
730
command changes its name or signature. Ideally only the tests for a
731
given command are affected when a given command is changed.
733
4. If you have a test which does actually require running bzr in a
734
subprocess you can use ``run_bzr_subprocess``. By default the spawned
735
process will not load plugins unless ``--allow-plugins`` is supplied.
741
We have a rich collection of tools to support writing tests. Please use
742
them in preference to ad-hoc solutions as they provide portability and
743
performance benefits.
748
The ``TreeBuilder`` interface allows the construction of arbitrary trees
749
with a declarative interface. A sample session might look like::
751
tree = self.make_branch_and_tree('path')
752
builder = TreeBuilder()
753
builder.start_tree(tree)
754
builder.build(['foo', "bar/", "bar/file"])
755
tree.commit('commit the tree')
756
builder.finish_tree()
758
Please see bzrlib.treebuilder for more details.
763
The ``BranchBuilder`` interface allows the creation of test branches in a
764
quick and easy manner. A sample session::
766
builder = BranchBuilder(self.get_transport().clone('relpath'))
767
builder.build_commit()
768
builder.build_commit()
769
builder.build_commit()
770
branch = builder.get_branch()
772
Please see bzrlib.branchbuilder for more details.
777
We make selective use of doctests__. In general they should provide
778
*examples* within the API documentation which can incidentally be tested. We
779
don't try to test every important case using doctests -- regular Python
780
tests are generally a better solution.
782
Most of these are in ``bzrlib/doc/api``. More additions are welcome.
784
__ http://docs.python.org/lib/module-doctest.html
789
Currently, bzr selftest is used to invoke tests.
790
You can provide a pattern argument to run a subset. For example,
791
to run just the blackbox tests, run::
793
./bzr selftest -v blackbox
795
To skip a particular test (or set of tests), use the --exclude option
796
(shorthand -x) like so::
798
./bzr selftest -v -x blackbox
800
To list tests without running them, use the --list-only option like so::
802
./bzr selftest --list-only
804
This option can be combined with other selftest options (like -x) and
805
filter patterns to understand their effect.
696
808
Handling Errors and Exceptions
697
809
==============================
added
removed
doc/developers/HACKING
