~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Aaron Bentley
  • Date: 2008-10-11 17:52:14 UTC
  • mto: This revision was merged to the branch mainline in revision 3823.
  • Revision ID: aaron@aaronbentley.com-20081011175214-85vfxt61753sp404
Make status nicer by not shelving lines for files not being changed

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
====================
2
 
Bazaar Testing Guide
3
 
====================
4
 
 
5
 
 
6
 
The Importance of Testing
7
 
=========================
8
 
 
9
 
Reliability is a critical success factor for any Version Control System.
10
 
We want Bazaar to be highly reliable across multiple platforms while
11
 
evolving over time to meet the needs of its community.
12
 
 
13
 
In a nutshell, this is what we expect and encourage:
14
 
 
15
 
* New functionality should have test cases.  Preferably write the
16
 
  test before writing the code.
17
 
 
18
 
  In general, you can test at either the command-line level or the
19
 
  internal API level.  See `Writing tests`_ below for more detail.
20
 
 
21
 
* Try to practice Test-Driven Development: before fixing a bug, write a
22
 
  test case so that it does not regress.  Similarly for adding a new
23
 
  feature: write a test case for a small version of the new feature before
24
 
  starting on the code itself.  Check the test fails on the old code, then
25
 
  add the feature or fix and check it passes.
26
 
 
27
 
By doing these things, the Bazaar team gets increased confidence that
28
 
changes do what they claim to do, whether provided by the core team or
29
 
by community members. Equally importantly, we can be surer that changes
30
 
down the track do not break new features or bug fixes that you are
31
 
contributing today.
32
 
 
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?
37
 
 
38
 
 
39
 
Running the Test Suite
40
 
======================
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
 
 
60
 
Currently, bzr selftest is used to invoke tests.
61
 
You can provide a pattern argument to run a subset. For example,
62
 
to run just the blackbox tests, run::
63
 
 
64
 
  ./bzr selftest -v blackbox
65
 
 
66
 
To skip a particular test (or set of tests), use the --exclude option
67
 
(shorthand -x) like so::
68
 
 
69
 
  ./bzr selftest -v -x blackbox
70
 
 
71
 
To ensure that all tests are being run and succeeding, you can use the
72
 
--strict option which will fail if there are any missing features or known
73
 
failures, like so::
74
 
 
75
 
  ./bzr selftest --strict
76
 
 
77
 
To list tests without running them, use the --list-only option like so::
78
 
 
79
 
  ./bzr selftest --list-only
80
 
 
81
 
This option can be combined with other selftest options (like -x) and
82
 
filter patterns to understand their effect.
83
 
 
84
 
Once you understand how to create a list of tests, you can use the --load-list
85
 
option to run only a restricted set of tests that you kept in a file, one test
86
 
id by line. Keep in mind that this will never be sufficient to validate your
87
 
modifications, you still need to run the full test suite for that, but using it
88
 
can help in some cases (like running only the failed tests for some time)::
89
 
 
90
 
  ./bzr selftest -- load-list my_failing_tests
91
 
 
92
 
This option can also be combined with other selftest options, including
93
 
patterns. It has some drawbacks though, the list can become out of date pretty
94
 
quick when doing Test Driven Development.
95
 
 
96
 
To address this concern, there is another way to run a restricted set of tests:
97
 
the --starting-with option will run only the tests whose name starts with the
98
 
specified string. It will also avoid loading the other tests and as a
99
 
consequence starts running your tests quicker::
100
 
 
101
 
  ./bzr selftest --starting-with bzrlib.blackbox
102
 
 
103
 
This option can be combined with all the other selftest options including
104
 
--load-list. The later is rarely used but allows to run a subset of a list of
105
 
failing tests for example.
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
 
 
128
 
 
129
 
Test suite debug flags
130
 
----------------------
131
 
 
132
 
Similar to the global ``-Dfoo`` debug options, bzr selftest accepts
133
 
``-E=foo`` debug flags.  These flags are:
134
 
 
135
 
:allow_debug: do *not* clear the global debug flags when running a test.
136
 
  This can provide useful logging to help debug test failures when used
137
 
  with e.g. ``bzr -Dhpss selftest -E=allow_debug``
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
 
 
152
 
 
153
 
Writing Tests
154
 
=============
155
 
 
156
 
Normally you should add or update a test for all bug fixes or new features
157
 
in Bazaar.
158
 
 
159
 
 
160
 
Where should I put a new test?
161
 
------------------------------
162
 
 
163
 
Bzrlib's tests are organised by the type of test.  Most of the tests in
164
 
bzr's test suite belong to one of these categories:
165
 
 
166
 
 - Unit tests
167
 
 - Blackbox (UI) tests
168
 
 - Per-implementation tests
169
 
 - Doctests
170
 
 
171
 
A quick description of these test types and where they belong in bzrlib's
172
 
source follows.  Not all tests fall neatly into one of these categories;
173
 
in those cases use your judgement.
174
 
 
175
 
 
176
 
Unit tests
177
 
~~~~~~~~~~
178
 
 
179
 
Unit tests make up the bulk of our test suite.  These are tests that are
180
 
focused on exercising a single, specific unit of the code as directly
181
 
as possible.  Each unit test is generally fairly short and runs very
182
 
quickly.
183
 
 
184
 
They are found in ``bzrlib/tests/test_*.py``.  So in general tests should
185
 
be placed in a file named test_FOO.py where FOO is the logical thing under
186
 
test.
187
 
 
188
 
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
189
 
See bzrlib/tests/test_sampler.py for a template test script.
190
 
 
191
 
 
192
 
Blackbox (UI) tests
193
 
~~~~~~~~~~~~~~~~~~~
194
 
 
195
 
Tests can be written for the UI or for individual areas of the library.
196
 
Choose whichever is appropriate: if adding a new command, or a new command
197
 
option, then you should be writing a UI test.  If you are both adding UI
198
 
functionality and library functionality, you will want to write tests for
199
 
both the UI and the core behaviours.  We call UI tests 'blackbox' tests
200
 
and they belong in ``bzrlib/tests/blackbox/*.py``.
201
 
 
202
 
When writing blackbox tests please honour the following conventions:
203
 
 
204
 
 1. Place the tests for the command 'name' in
205
 
    bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
206
 
    to locate the test script for a faulty command.
207
 
 
208
 
 2. Use the 'self.run_bzr("name")' utility function to invoke the command
209
 
    rather than running bzr in a subprocess or invoking the
210
 
    cmd_object.run() method directly. This is a lot faster than
211
 
    subprocesses and generates the same logging output as running it in a
212
 
    subprocess (which invoking the method directly does not).
213
 
 
214
 
 3. Only test the one command in a single test script. Use the bzrlib
215
 
    library when setting up tests and when evaluating the side-effects of
216
 
    the command. We do this so that the library api has continual pressure
217
 
    on it to be as functional as the command line in a simple manner, and
218
 
    to isolate knock-on effects throughout the blackbox test suite when a
219
 
    command changes its name or signature. Ideally only the tests for a
220
 
    given command are affected when a given command is changed.
221
 
 
222
 
 4. If you have a test which does actually require running bzr in a
223
 
    subprocess you can use ``run_bzr_subprocess``. By default the spawned
224
 
    process will not load plugins unless ``--allow-plugins`` is supplied.
225
 
 
226
 
 
227
 
Per-implementation tests
228
 
~~~~~~~~~~~~~~~~~~~~~~~~
229
 
 
230
 
Per-implementation tests are tests that are defined once and then run
231
 
against multiple implementations of an interface.  For example,
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``.
235
 
 
236
 
These are really a sub-category of unit tests, but an important one.
237
 
 
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.
246
 
 
247
 
 
248
 
Doctests
249
 
~~~~~~~~
250
 
 
251
 
We make selective use of doctests__.  In general they should provide
252
 
*examples* within the API documentation which can incidentally be tested.  We
253
 
don't try to test every important case using doctests |--| regular Python
254
 
tests are generally a better solution.  That is, we just use doctests to
255
 
make our documentation testable, rather than as a way to make tests.
256
 
 
257
 
Most of these are in ``bzrlib/doc/api``.  More additions are welcome.
258
 
 
259
 
  __ http://docs.python.org/lib/module-doctest.html
260
 
 
261
 
 
262
 
Shell-like tests
263
 
----------------
264
 
 
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.
268
 
 
269
 
A script is a set of commands, each command is composed of:
270
 
 
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.
275
 
 
276
 
Input, output and error lines can be specified in any order.
277
 
 
278
 
Except for the expected output, all lines start with a special
279
 
string (based on their origin when used under a Unix shell):
280
 
 
281
 
 * '$ ' for the command,
282
 
 * '<' for input,
283
 
 * nothing for output,
284
 
 * '2>' for errors,
285
 
 
286
 
Comments can be added anywhere, they start with '#' and end with
287
 
the line.
288
 
 
289
 
The execution stops as soon as an expected output or an expected error is not
290
 
matched.
291
 
 
292
 
When no output is specified, any ouput from the command is accepted
293
 
and execution continue.
294
 
 
295
 
If an error occurs and no expected error is specified, the execution stops.
296
 
 
297
 
An error is defined by a returned status different from zero, not by the
298
 
presence of text on the error stream.
299
 
 
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.
302
 
 
303
 
Examples:
304
 
 
305
 
The following will succeeds only if 'bzr add' outputs 'adding file'::
306
 
 
307
 
  $ bzr add file
308
 
  >adding file
309
 
 
310
 
If you want the command to succeed for any output, just use::
311
 
 
312
 
  $ bzr add file
313
 
 
314
 
The following will stop with an error::
315
 
 
316
 
  $ bzr not-a-command
317
 
 
318
 
If you want it to succeed, use::
319
 
 
320
 
  $ bzr not-a-command
321
 
  2> bzr: ERROR: unknown command "not-a-command"
322
 
 
323
 
You can use ellipsis (...) to replace any piece of text you don't want to be
324
 
matched exactly::
325
 
 
326
 
  $ bzr branch not-a-branch
327
 
  2>bzr: ERROR: Not a branch...not-a-branch/".
328
 
 
329
 
This can be used to ignore entire lines too::
330
 
 
331
 
  $ cat
332
 
  <first line
333
 
  <second line
334
 
  <third line
335
 
  # And here we explain that surprising fourth line
336
 
  <fourth line
337
 
  <last line
338
 
  >first line
339
 
  >...
340
 
  >last line
341
 
 
342
 
You can check the content of a file with cat::
343
 
 
344
 
  $ cat <file
345
 
  >expected content
346
 
 
347
 
You can also check the existence of a file with cat, the following will fail if
348
 
the file doesn't exist::
349
 
 
350
 
  $ cat file
351
 
 
352
 
The actual use of ScriptRunner within a TestCase looks something like
353
 
this::
354
 
 
355
 
        def test_unshelve_keep(self):
356
 
                # some setup here
357
 
                sr = ScriptRunner()
358
 
                sr.run_script(self, '''
359
 
        $ bzr add file
360
 
        $ bzr shelve --all -m Foo
361
 
        $ bzr shelve --list
362
 
        1: Foo
363
 
        $ bzr unshelve --keep
364
 
        $ bzr shelve --list
365
 
        1: Foo
366
 
        $ cat file
367
 
        contents of file
368
 
        ''')
369
 
 
370
 
 
371
 
 
372
 
.. Effort tests
373
 
.. ~~~~~~~~~~~~
374
 
 
375
 
 
376
 
 
377
 
Skipping tests
378
 
--------------
379
 
 
380
 
In our enhancements to unittest we allow for some addition results beyond
381
 
just success or failure.
382
 
 
383
 
If a test can't be run, it can say that it's skipped by raising a special
384
 
exception.  This is typically used in parameterized tests |--| for example
385
 
if a transport doesn't support setting permissions, we'll skip the tests
386
 
that relating to that.  ::
387
 
 
388
 
    try:
389
 
        return self.branch_format.initialize(repo.bzrdir)
390
 
    except errors.UninitializableFormat:
391
 
        raise tests.TestSkipped('Uninitializable branch format')
392
 
 
393
 
Raising TestSkipped is a good idea when you want to make it clear that the
394
 
test was not run, rather than just returning which makes it look as if it
395
 
was run and passed.
396
 
 
397
 
Several different cases are distinguished:
398
 
 
399
 
TestSkipped
400
 
        Generic skip; the only type that was present up to bzr 0.18.
401
 
 
402
 
TestNotApplicable
403
 
        The test doesn't apply to the parameters with which it was run.
404
 
        This is typically used when the test is being applied to all
405
 
        implementations of an interface, but some aspects of the interface
406
 
        are optional and not present in particular concrete
407
 
        implementations.  (Some tests that should raise this currently
408
 
        either silently return or raise TestSkipped.)  Another option is
409
 
        to use more precise parameterization to avoid generating the test
410
 
        at all.
411
 
 
412
 
UnavailableFeature
413
 
        The test can't be run because a dependency (typically a Python
414
 
        library) is not available in the test environment.  These
415
 
        are in general things that the person running the test could fix
416
 
        by installing the library.  It's OK if some of these occur when
417
 
        an end user runs the tests or if we're specifically testing in a
418
 
        limited environment, but a full test should never see them.
419
 
 
420
 
        See `Test feature dependencies`_ below.
421
 
 
422
 
KnownFailure
423
 
        The test exists but is known to fail, for example this might be
424
 
        appropriate to raise if you've committed a test for a bug but not
425
 
        the fix for it, or if something works on Unix but not on Windows.
426
 
 
427
 
        Raising this allows you to distinguish these failures from the
428
 
        ones that are not expected to fail.  If the test would fail
429
 
        because of something we don't expect or intend to fix,
430
 
        KnownFailure is not appropriate, and TestNotApplicable might be
431
 
        better.
432
 
 
433
 
        KnownFailure should be used with care as we don't want a
434
 
        proliferation of quietly broken tests.
435
 
 
436
 
 
437
 
 
438
 
We plan to support three modes for running the test suite to control the
439
 
interpretation of these results.  Strict mode is for use in situations
440
 
like merges to the mainline and releases where we want to make sure that
441
 
everything that can be tested has been tested.  Lax mode is for use by
442
 
developers who want to temporarily tolerate some known failures.  The
443
 
default behaviour is obtained by ``bzr selftest`` with no options, and
444
 
also (if possible) by running under another unittest harness.
445
 
 
446
 
======================= ======= ======= ========
447
 
result                  strict  default lax
448
 
======================= ======= ======= ========
449
 
TestSkipped             pass    pass    pass
450
 
TestNotApplicable       pass    pass    pass
451
 
UnavailableFeature      fail    pass    pass
452
 
KnownFailure            fail    pass    pass
453
 
======================= ======= ======= ========
454
 
 
455
 
 
456
 
Test feature dependencies
457
 
-------------------------
458
 
 
459
 
Writing tests that require a feature
460
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461
 
 
462
 
Rather than manually checking the environment in each test, a test class
463
 
can declare its dependence on some test features.  The feature objects are
464
 
checked only once for each run of the whole test suite.
465
 
 
466
 
(For historical reasons, as of May 2007 many cases that should depend on
467
 
features currently raise TestSkipped.)
468
 
 
469
 
For example::
470
 
 
471
 
    class TestStrace(TestCaseWithTransport):
472
 
 
473
 
        _test_needs_features = [StraceFeature]
474
 
 
475
 
This means all tests in this class need the feature.  If the feature is
476
 
not available the test will be skipped using UnavailableFeature.
477
 
 
478
 
Individual tests can also require a feature using the ``requireFeature``
479
 
method::
480
 
 
481
 
    self.requireFeature(StraceFeature)
482
 
 
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
497
 
 - CaseInsensitiveFilesystemFeature.
498
 
 
499
 
 
500
 
Defining a new feature that tests can require
501
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
502
 
 
503
 
New features for use with ``_test_needs_features`` or ``requireFeature``
504
 
are defined by subclassing ``bzrlib.tests.Feature`` and overriding the
505
 
``_probe`` and ``feature_name`` methods.  For example::
506
 
 
507
 
    class _SymlinkFeature(Feature):
508
 
 
509
 
        def _probe(self):
510
 
            return osutils.has_symlinks()
511
 
 
512
 
        def feature_name(self):
513
 
            return 'symlinks'
514
 
 
515
 
    SymlinkFeature = _SymlinkFeature()
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
 
 
532
 
 
533
 
Testing exceptions and errors
534
 
-----------------------------
535
 
 
536
 
It's important to test handling of errors and exceptions.  Because this
537
 
code is often not hit in ad-hoc testing it can often have hidden bugs --
538
 
it's particularly common to get NameError because the exception code
539
 
references a variable that has since been renamed.
540
 
 
541
 
.. TODO: Something about how to provoke errors in the right way?
542
 
 
543
 
In general we want to test errors at two levels:
544
 
 
545
 
1. A test in ``test_errors.py`` checking that when the exception object is
546
 
   constructed with known parameters it produces an expected string form.
547
 
   This guards against mistakes in writing the format string, or in the
548
 
   ``str`` representations of its parameters.  There should be one for
549
 
   each exception class.
550
 
 
551
 
2. Tests that when an api is called in a particular situation, it raises
552
 
   an error of the expected class.  You should typically use
553
 
   ``assertRaises``, which in the Bazaar test suite returns the exception
554
 
   object to allow you to examine its parameters.
555
 
 
556
 
In some cases blackbox tests will also want to check error reporting.  But
557
 
it can be difficult to provoke every error through the commandline
558
 
interface, so those tests are only done as needed |--| eg in response to a
559
 
particular bug or if the error is reported in an unusual way(?)  Blackbox
560
 
tests should mostly be testing how the command-line interface works, so
561
 
should only test errors if there is something particular to the cli in how
562
 
they're displayed or handled.
563
 
 
564
 
 
565
 
Testing warnings
566
 
----------------
567
 
 
568
 
The Python ``warnings`` module is used to indicate a non-fatal code
569
 
problem.  Code that's expected to raise a warning can be tested through
570
 
callCatchWarnings.
571
 
 
572
 
The test suite can be run with ``-Werror`` to check no unexpected errors
573
 
occur.
574
 
 
575
 
However, warnings should be used with discretion.  It's not an appropriate
576
 
way to give messages to the user, because the warning is normally shown
577
 
only once per source line that causes the problem.  You should also think
578
 
about whether the warning is serious enought that it should be visible to
579
 
users who may not be able to fix it.
580
 
 
581
 
 
582
 
Interface implementation testing and test scenarios
583
 
---------------------------------------------------
584
 
 
585
 
There are several cases in Bazaar of multiple implementations of a common
586
 
conceptual interface.  ("Conceptual" because it's not necessary for all
587
 
the implementations to share a base class, though they often do.)
588
 
Examples include transports and the working tree, branch and repository
589
 
classes.
590
 
 
591
 
In these cases we want to make sure that every implementation correctly
592
 
fulfils the interface requirements.  For example, every Transport should
593
 
support the ``has()`` and ``get()`` and ``clone()`` methods.  We have a
594
 
sub-suite of tests in ``test_transport_implementations``.  (Most
595
 
per-implementation tests are in submodules of ``bzrlib.tests``, but not
596
 
the transport tests at the moment.)
597
 
 
598
 
These tests are repeated for each registered Transport, by generating a
599
 
new TestCase instance for the cross product of test methods and transport
600
 
implementations.  As each test runs, it has ``transport_class`` and
601
 
``transport_server`` set to the class it should test.  Most tests don't
602
 
access these directly, but rather use ``self.get_transport`` which returns
603
 
a transport of the appropriate type.
604
 
 
605
 
The goal is to run per-implementation only the tests that relate to that
606
 
particular interface.  Sometimes we discover a bug elsewhere that happens
607
 
with only one particular transport.  Once it's isolated, we can consider
608
 
whether a test should be added for that particular implementation,
609
 
or for all implementations of the interface.
610
 
 
611
 
The multiplication of tests for different implementations is normally
612
 
accomplished by overriding the ``load_tests`` function used to load tests
613
 
from a module.  This function typically loads all the tests, then applies
614
 
a TestProviderAdapter to them, which generates a longer suite containing
615
 
all the test variations.
616
 
 
617
 
See also `Per-implementation tests`_ (above).
618
 
 
619
 
 
620
 
Test scenarios
621
 
--------------
622
 
 
623
 
Some utilities are provided for generating variations of tests.  This can
624
 
be used for per-implementation tests, or other cases where the same test
625
 
code needs to run several times on different scenarios.
626
 
 
627
 
The general approach is to define a class that provides test methods,
628
 
which depend on attributes of the test object being pre-set with the
629
 
values to which the test should be applied.  The test suite should then
630
 
also provide a list of scenarios in which to run the tests.
631
 
 
632
 
Typically ``multiply_tests_from_modules`` should be called from the test
633
 
module's ``load_tests`` function.
634
 
 
635
 
 
636
 
Test support
637
 
------------
638
 
 
639
 
We have a rich collection of tools to support writing tests. Please use
640
 
them in preference to ad-hoc solutions as they provide portability and
641
 
performance benefits.
642
 
 
643
 
 
644
 
TestCase and its subclasses
645
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~
646
 
 
647
 
The ``bzrlib.tests`` module defines many TestCase classes to help you
648
 
write your tests.
649
 
 
650
 
TestCase
651
 
    A base TestCase that extends the Python standard library's
652
 
    TestCase in several ways.  It adds more assertion methods (e.g.
653
 
    ``assertContainsRe``), ``addCleanup``, and other features (see its API
654
 
    docs for details).  It also has a ``setUp`` that makes sure that
655
 
    global state like registered hooks and loggers won't interfere with
656
 
    your test.  All tests should use this base class (whether directly or
657
 
    via a subclass).
658
 
 
659
 
TestCaseWithMemoryTransport
660
 
    Extends TestCase and adds methods like ``get_transport``,
661
 
    ``make_branch`` and ``make_branch_builder``.  The files created are
662
 
    stored in a MemoryTransport that is discarded at the end of the test.
663
 
    This class is good for tests that need to make branches or use
664
 
    transports, but that don't require storing things on disk.  All tests
665
 
    that create bzrdirs should use this base class (either directly or via
666
 
    a subclass) as it ensures that the test won't accidentally operate on
667
 
    real branches in your filesystem.
668
 
 
669
 
TestCaseInTempDir
670
 
    Extends TestCaseWithMemoryTransport.  For tests that really do need
671
 
    files to be stored on disk, e.g. because a subprocess uses a file, or
672
 
    for testing functionality that accesses the filesystem directly rather
673
 
    than via the Transport layer (such as dirstate).
674
 
 
675
 
TestCaseWithTransport
676
 
    Extends TestCaseInTempDir.  Provides ``get_url`` and
677
 
    ``get_readonly_url`` facilities.  Subclasses can control the
678
 
    transports used by setting ``vfs_transport_factory``,
679
 
    ``transport_server`` and/or ``transport_readonly_server``.
680
 
 
681
 
 
682
 
See the API docs for more details.
683
 
 
684
 
 
685
 
BranchBuilder
686
 
~~~~~~~~~~~~~
687
 
 
688
 
When writing a test for a feature, it is often necessary to set up a
689
 
branch with a certain history.  The ``BranchBuilder`` interface allows the
690
 
creation of test branches in a quick and easy manner.  Here's a sample
691
 
session::
692
 
 
693
 
  builder = self.make_branch_builder('relpath')
694
 
  builder.build_commit()
695
 
  builder.build_commit()
696
 
  builder.build_commit()
697
 
  branch = builder.get_branch()
698
 
 
699
 
``make_branch_builder`` is a method of ``TestCaseWithMemoryTransport``.
700
 
 
701
 
Note that many current tests create test branches by inheriting from
702
 
``TestCaseWithTransport`` and using the ``make_branch_and_tree`` helper to
703
 
give them a ``WorkingTree`` that they can commit to. However, using the
704
 
newer ``make_branch_builder`` helper is preferred, because it can build
705
 
the changes in memory, rather than on disk. Tests that are explictly
706
 
testing how we work with disk objects should, of course, use a real
707
 
``WorkingTree``.
708
 
 
709
 
Please see bzrlib.branchbuilder for more details.
710
 
 
711
 
If you're going to examine the commit timestamps e.g. in a test for log
712
 
output, you should set the timestamp on the tree, rather than using fuzzy
713
 
matches in the test.
714
 
 
715
 
 
716
 
TreeBuilder
717
 
~~~~~~~~~~~
718
 
 
719
 
The ``TreeBuilder`` interface allows the construction of arbitrary trees
720
 
with a declarative interface. A sample session might look like::
721
 
 
722
 
  tree = self.make_branch_and_tree('path')
723
 
  builder = TreeBuilder()
724
 
  builder.start_tree(tree)
725
 
  builder.build(['foo', "bar/", "bar/file"])
726
 
  tree.commit('commit the tree')
727
 
  builder.finish_tree()
728
 
 
729
 
Usually a test will create a tree using ``make_branch_and_memory_tree`` (a
730
 
method of ``TestCaseWithMemoryTransport``) or ``make_branch_and_tree`` (a
731
 
method of ``TestCaseWithTransport``).
732
 
 
733
 
Please see bzrlib.treebuilder for more details.
734
 
 
735
 
 
736
 
.. |--| unicode:: U+2014
737
 
 
738
 
..
739
 
   vim: ft=rst tw=74 ai