34
30
down the track do not break new features or bug fixes that you are
35
31
contributing today.
37
As of May 2008, Bazaar ships with a test suite containing over 12000 tests
38
and growing. We are proud of it and want to remain so. As community
39
members, we all benefit from it. Would you trust version control on
40
your project to a product *without* a test suite like Bazaar has?
33
As of September 2009, Bazaar ships with a test suite containing over
34
23,000 tests and growing. We are proud of it and want to remain so. As
35
community members, we all benefit from it. Would you trust version control
36
on your project to a product *without* a test suite like Bazaar has?
43
39
Running the Test Suite
44
40
======================
42
As of Bazaar 2.1, you must have the testtools_ library installed to run
45
.. _testtools: https://launchpad.net/testtools/
47
To test all of Bazaar, just run::
51
With ``--verbose`` bzr will print the name of every test as it is run.
53
This should always pass, whether run from a source tree or an installed
54
copy of Bazaar. Please investigate and/or report any failures.
57
Running particular tests
58
------------------------
46
60
Currently, bzr selftest is used to invoke tests.
47
61
You can provide a pattern argument to run a subset. For example,
48
62
to run just the blackbox tests, run::
90
104
--load-list. The later is rarely used but allows to run a subset of a list of
91
105
failing tests for example.
110
To test only the bzr core, ignoring any plugins you may have installed,
113
./bzr --no-plugins selftest
115
Disabling crash reporting
116
-------------------------
118
By default Bazaar uses apport_ to report program crashes. In developing
119
Bazaar it's normal and expected to have it crash from time to time, at
120
least because a test failed if for no other reason.
122
Therefore you should probably add ``debug_flags = no_apport`` to your
123
``bazaar.conf`` file (in ``~/.bazaar/`` on Unix), so that failures just
124
print a traceback rather than writing a crash file.
126
.. _apport: https://launchpad.net/apport/
94
129
Test suite debug flags
95
130
----------------------
101
136
This can provide useful logging to help debug test failures when used
102
137
with e.g. ``bzr -Dhpss selftest -E=allow_debug``
139
Note that this will probably cause some tests to fail, because they
140
don't expect to run with any debug flags on.
146
Bazaar can optionally produce output in the machine-readable subunit_
147
format, so that test output can be post-processed by various tools.
149
.. _subunit: https://launchpad.net/subunit/
156
Normally you should add or update a test for all bug fixes or new features
108
160
Where should I put a new test?
109
161
------------------------------
158
210
cmd_object.run() method directly. This is a lot faster than
159
211
subprocesses and generates the same logging output as running it in a
160
212
subprocess (which invoking the method directly does not).
162
214
3. Only test the one command in a single test script. Use the bzrlib
163
215
library when setting up tests and when evaluating the side-effects of
164
216
the command. We do this so that the library api has continual pressure
178
230
Per-implementation tests are tests that are defined once and then run
179
231
against multiple implementations of an interface. For example,
180
``test_transport_implementations.py`` defines tests that all Transport
181
implementations (local filesystem, HTTP, and so on) must pass.
183
They are found in ``bzrlib/tests/*_implementations/test_*.py``,
184
``bzrlib/tests/per_*/*.py``, and
185
``bzrlib/tests/test_*_implementations.py``.
232
``per_transport.py`` defines tests that all Transport implementations
233
(local filesystem, HTTP, and so on) must pass. They are found in
234
``bzrlib/tests/per_*/*.py``, and ``bzrlib/tests/per_*.py``.
187
236
These are really a sub-category of unit tests, but an important one.
238
Along the same lines are tests for extension modules. We generally have
239
both a pure-python and a compiled implementation for each module. As such,
240
we want to run the same tests against both implementations. These can
241
generally be found in ``bzrlib/tests/*__*.py`` since extension modules are
242
usually prefixed with an underscore. Since there are only two
243
implementations, we have a helper function
244
``bzrlib.tests.permute_for_extension``, which can simplify the
245
``load_tests`` implementation.
201
259
__ http://docs.python.org/lib/module-doctest.html
265
``bzrlib/tests/script.py`` allows users to write tests in a syntax very close to a shell session,
266
using a restricted and limited set of commands that should be enough to mimic
267
most of the behaviours.
269
A script is a set of commands, each command is composed of:
271
* one mandatory command line,
272
* one optional set of input lines to feed the command,
273
* one optional set of output expected lines,
274
* one optional set of error expected lines.
276
Input, output and error lines can be specified in any order.
278
Except for the expected output, all lines start with a special
279
string (based on their origin when used under a Unix shell):
281
* '$ ' for the command,
283
* nothing for output,
286
Comments can be added anywhere, they start with '#' and end with
289
The execution stops as soon as an expected output or an expected error is not
292
When no output is specified, any ouput from the command is accepted
293
and execution continue.
295
If an error occurs and no expected error is specified, the execution stops.
297
An error is defined by a returned status different from zero, not by the
298
presence of text on the error stream.
300
The matching is done on a full string comparison basis unless '...' is used, in
301
which case expected output/errors can be less precise.
305
The following will succeeds only if 'bzr add' outputs 'adding file'::
310
If you want the command to succeed for any output, just use::
314
The following will stop with an error::
318
If you want it to succeed, use::
321
2> bzr: ERROR: unknown command "not-a-command"
323
You can use ellipsis (...) to replace any piece of text you don't want to be
326
$ bzr branch not-a-branch
327
2>bzr: ERROR: Not a branch...not-a-branch/".
329
This can be used to ignore entire lines too::
335
# And here we explain that surprising fourth line
342
You can check the content of a file with cat::
347
You can also check the existence of a file with cat, the following will fail if
348
the file doesn't exist::
352
The actual use of ScriptRunner within a TestCase looks something like
355
def test_unshelve_keep(self):
358
sr.run_script(self, '''
360
$ bzr shelve --all -m Foo
363
$ bzr unshelve --keep
255
423
The test exists but is known to fail, for example this might be
256
424
appropriate to raise if you've committed a test for a bug but not
257
425
the fix for it, or if something works on Unix but not on Windows.
259
427
Raising this allows you to distinguish these failures from the
260
428
ones that are not expected to fail. If the test would fail
261
429
because of something we don't expect or intend to fix,
265
433
KnownFailure should be used with care as we don't want a
266
434
proliferation of quietly broken tests.
268
438
We plan to support three modes for running the test suite to control the
269
439
interpretation of these results. Strict mode is for use in situations
270
440
like merges to the mainline and releases where we want to make sure that
311
481
self.requireFeature(StraceFeature)
313
Features already defined in bzrlib.tests include:
318
- UnicodeFilenameFeature,
319
- FTPServerFeature, and
483
The old naming style for features is CamelCase, but because they're
484
actually instances not classses they're now given instance-style names
487
Features already defined in ``bzrlib.tests`` and ``bzrlib.tests.features``
495
- UnicodeFilenameFeature
320
497
- CaseInsensitiveFilesystemFeature.
328
505
``_probe`` and ``feature_name`` methods. For example::
330
507
class _SymlinkFeature(Feature):
332
509
def _probe(self):
333
510
return osutils.has_symlinks()
335
512
def feature_name(self):
336
513
return 'symlinks'
338
515
SymlinkFeature = _SymlinkFeature()
517
A helper for handling running tests based on whether a python
518
module is available. This can handle 3rd-party dependencies (is
519
``paramiko`` available?) as well as stdlib (``termios``) or
520
extension modules (``bzrlib._groupcompress_pyx``). You create a
521
new feature instance with::
523
# in bzrlib/tests/features.py
524
apport = tests.ModuleAvailableFeature('apport')
527
# then in bzrlib/tests/test_apport.py
528
class TestApportReporting(TestCaseInTempDir):
530
_test_needs_features = [features.apport]
341
533
Testing exceptions and errors
342
534
-----------------------------
added
removed
doc/developers/testing.txt
