693
693
should be only in the command-line tool.
700
Bazaar has online help for various topics through ``bzr help COMMAND`` or
701
equivalently ``bzr command -h``. We also have help on command options,
702
and on other help topics. (See ``help_topics.py``.)
704
As for python docstrings, the first paragraph should be a single-sentence
705
synopsis of the command.
707
The help for options should be one or more proper sentences, starting with
708
a capital letter and finishing with a full stop (period).
710
All help messages and documentation should have two spaces between
717
In general tests should be placed in a file named test_FOO.py where
718
FOO is the logical thing under test. That file should be placed in the
719
tests subdirectory under the package being tested.
721
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
722
See bzrlib/tests/test_sampler.py for a template test script.
724
Tests can be written for the UI or for individual areas of the library.
725
Choose whichever is appropriate: if adding a new command, or a new command
726
option, then you should be writing a UI test. If you are both adding UI
727
functionality and library functionality, you will want to write tests for
728
both the UI and the core behaviours. We call UI tests 'blackbox' tests
729
and they are found in ``bzrlib/tests/blackbox/*.py``.
731
When writing blackbox tests please honour the following conventions:
733
1. Place the tests for the command 'name' in
734
bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
735
to locate the test script for a faulty command.
737
2. Use the 'self.run_bzr("name")' utility function to invoke the command
738
rather than running bzr in a subprocess or invoking the
739
cmd_object.run() method directly. This is a lot faster than
740
subprocesses and generates the same logging output as running it in a
741
subprocess (which invoking the method directly does not).
743
3. Only test the one command in a single test script. Use the bzrlib
744
library when setting up tests and when evaluating the side-effects of
745
the command. We do this so that the library api has continual pressure
746
on it to be as functional as the command line in a simple manner, and
747
to isolate knock-on effects throughout the blackbox test suite when a
748
command changes its name or signature. Ideally only the tests for a
749
given command are affected when a given command is changed.
751
4. If you have a test which does actually require running bzr in a
752
subprocess you can use ``run_bzr_subprocess``. By default the spawned
753
process will not load plugins unless ``--allow-plugins`` is supplied.
759
We have a rich collection of tools to support writing tests. Please use
760
them in preference to ad-hoc solutions as they provide portability and
761
performance benefits.
766
The ``TreeBuilder`` interface allows the construction of arbitrary trees
767
with a declarative interface. A sample session might look like::
769
tree = self.make_branch_and_tree('path')
770
builder = TreeBuilder()
771
builder.start_tree(tree)
772
builder.build(['foo', "bar/", "bar/file"])
773
tree.commit('commit the tree')
774
builder.finish_tree()
776
Please see bzrlib.treebuilder for more details.
781
The ``BranchBuilder`` interface allows the creation of test branches in a
782
quick and easy manner. A sample session::
784
builder = BranchBuilder(self.get_transport().clone('relpath'))
785
builder.build_commit()
786
builder.build_commit()
787
builder.build_commit()
788
branch = builder.get_branch()
790
Please see bzrlib.branchbuilder for more details.
795
We make selective use of doctests__. In general they should provide
796
*examples* within the API documentation which can incidentally be tested. We
797
don't try to test every important case using doctests -- regular Python
798
tests are generally a better solution.
800
Most of these are in ``bzrlib/doc/api``. More additions are welcome.
802
__ http://docs.python.org/lib/module-doctest.html
807
Currently, bzr selftest is used to invoke tests.
808
You can provide a pattern argument to run a subset. For example,
809
to run just the blackbox tests, run::
811
./bzr selftest -v blackbox
813
To skip a particular test (or set of tests), use the --exclude option
814
(shorthand -x) like so::
816
./bzr selftest -v -x blackbox
818
To list tests without running them, use the --list-only option like so::
820
./bzr selftest --list-only
822
This option can be combined with other selftest options (like -x) and
823
filter patterns to understand their effect.
696
826
Handling Errors and Exceptions
697
827
==============================
added
removed
doc/developers/HACKING
