~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-02-04 17:16:17 UTC
  • mfrom: (5004.2.6 doc)
  • Revision ID: pqm@pqm.ubuntu.com-20100204171617-8mbadia84bys1fr6
(mbp) developer doc tweaks

Show diffs side-by-side

added added

removed removed

Lines of Context:
39
39
Running the Test Suite
40
40
======================
41
41
 
 
42
As of Bazaar 2.1, you must have the testtools_ library installed to run
 
43
the bzr test suite.
 
44
 
 
45
.. _testtools: https://launchpad.net/testtools/
 
46
 
 
47
To test all of Bazaar, just run::
 
48
 
 
49
  bzr selftest 
 
50
 
 
51
With ``--verbose`` bzr will print the name of every test as it is run.
 
52
 
 
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.
 
55
 
 
56
 
 
57
Running particular tests
 
58
------------------------
 
59
 
42
60
Currently, bzr selftest is used to invoke tests.
43
61
You can provide a pattern argument to run a subset. For example,
44
62
to run just the blackbox tests, run::
86
104
--load-list. The later is rarely used but allows to run a subset of a list of
87
105
failing tests for example.
88
106
 
 
107
Disabling plugins
 
108
-----------------
 
109
 
 
110
To test only the bzr core, ignoring any plugins you may have installed,
 
111
use::
 
112
 
 
113
  ./bzr --no-plugins selftest 
 
114
 
 
115
Disabling crash reporting
 
116
-------------------------
 
117
 
 
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.
 
121
 
 
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.
 
125
 
 
126
.. _apport: https://launchpad.net/apport/
 
127
 
89
128
 
90
129
Test suite debug flags
91
130
----------------------
97
136
  This can provide useful logging to help debug test failures when used
98
137
  with e.g. ``bzr -Dhpss selftest -E=allow_debug``
99
138
 
 
139
  Note that this will probably cause some tests to fail, because they
 
140
  don't expect to run with any debug flags on.
 
141
 
 
142
 
 
143
Using subunit
 
144
-------------
 
145
 
 
146
Bazaar can optionally produce output in the machine-readable subunit_
 
147
format, so that test output can be post-processed by various tools.
 
148
 
 
149
.. _subunit: https://launchpad.net/subunit/
 
150
 
 
151
 
100
152
 
101
153
Writing Tests
102
154
=============
103
155
 
 
156
Normally you should add or update a test for all bug fixes or new features
 
157
in Bazaar.
 
158
 
 
159
 
104
160
Where should I put a new test?
105
161
------------------------------
106
162
 
377
433
        KnownFailure should be used with care as we don't want a
378
434
        proliferation of quietly broken tests.
379
435
 
380
 
ModuleAvailableFeature
381
 
        A helper for handling running tests based on whether a python
382
 
        module is available. This can handle 3rd-party dependencies (is
383
 
        ``paramiko`` available?) as well as stdlib (``termios``) or
384
 
        extension modules (``bzrlib._groupcompress_pyx``). You create a
385
 
        new feature instance with::
386
 
 
387
 
            MyModuleFeature = ModuleAvailableFeature('bzrlib.something')
388
 
 
389
 
            ...
390
 
            def test_something(self):
391
 
                self.requireFeature(MyModuleFeature)
392
 
                something = MyModuleFeature.module
393
436
 
394
437
 
395
438
We plan to support three modes for running the test suite to control the
437
480
 
438
481
    self.requireFeature(StraceFeature)
439
482
 
440
 
Features already defined in bzrlib.tests include:
441
 
 
442
 
 - SymlinkFeature,
443
 
 - HardlinkFeature,
444
 
 - OsFifoFeature,
445
 
 - UnicodeFilenameFeature,
446
 
 - 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
 
485
like ``apport``.
 
486
 
 
487
Features already defined in ``bzrlib.tests`` and ``bzrlib.tests.features``
 
488
include:
 
489
 
 
490
 - apport
 
491
 - paramiko
 
492
 - SymlinkFeature
 
493
 - HardlinkFeature
 
494
 - OsFifoFeature
 
495
 - UnicodeFilenameFeature
 
496
 - FTPServerFeature
447
497
 - CaseInsensitiveFilesystemFeature.
448
498
 
449
499
 
464
514
 
465
515
    SymlinkFeature = _SymlinkFeature()
466
516
 
 
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::
 
522
 
 
523
    # in bzrlib/tests/features.py
 
524
    apport = tests.ModuleAvailableFeature('apport')
 
525
 
 
526
 
 
527
    # then in bzrlib/tests/test_apport.py
 
528
    class TestApportReporting(TestCaseInTempDir):
 
529
 
 
530
        _test_needs_features = [features.apport]
 
531
 
467
532
 
468
533
Testing exceptions and errors
469
534
-----------------------------