/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Andrew Bennetts
  • Date: 2010-01-12 03:53:21 UTC
  • mfrom: (4948 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4964.
  • Revision ID: andrew.bennetts@canonical.com-20100112035321-hofpz5p10224ryj3
Merge lp:bzr, resolving conflicts.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/testing.txt
1
 
=======================
2
 
Guide to Testing Bazaar
3
 
=======================
4
 
 
5
 
.. contents::
6
 
 
7
 
Testing Bazaar
8
 
##############
 
1
====================
 
2
Bazaar Testing Guide
 
3
====================
 
4
 
9
5
 
10
6
The Importance of Testing
11
7
=========================
34
30
down the track do not break new features or bug fixes that you are
35
31
contributing today.
36
32
 
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?
41
37
 
42
38
 
43
39
Running the Test Suite
158
154
    cmd_object.run() method directly. This is a lot faster than
159
155
    subprocesses and generates the same logging output as running it in a
160
156
    subprocess (which invoking the method directly does not).
161
 
 
 
157
 
162
158
 3. Only test the one command in a single test script. Use the bzrlib
163
159
    library when setting up tests and when evaluating the side-effects of
164
160
    the command. We do this so that the library api has continual pressure
177
173
 
178
174
Per-implementation tests are tests that are defined once and then run
179
175
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.
182
 
 
183
 
They are found in ``bzrlib/tests/*_implementations/test_*.py``,
184
 
``bzrlib/tests/per_*/*.py``, and
185
 
``bzrlib/tests/test_*_implementations.py``.
 
176
``per_transport.py`` defines tests that all Transport implementations
 
177
(local filesystem, HTTP, and so on) must pass. They are found in
 
178
``bzrlib/tests/per_*/*.py``, and ``bzrlib/tests/per_*.py``.
186
179
 
187
180
These are really a sub-category of unit tests, but an important one.
188
181
 
 
182
Along the same lines are tests for extension modules. We generally have
 
183
both a pure-python and a compiled implementation for each module. As such,
 
184
we want to run the same tests against both implementations. These can
 
185
generally be found in ``bzrlib/tests/*__*.py`` since extension modules are
 
186
usually prefixed with an underscore. Since there are only two
 
187
implementations, we have a helper function
 
188
``bzrlib.tests.permute_for_extension``, which can simplify the
 
189
``load_tests`` implementation.
 
190
 
189
191
 
190
192
Doctests
191
193
~~~~~~~~
201
203
  __ http://docs.python.org/lib/module-doctest.html
202
204
 
203
205
 
 
206
Shell-like tests
 
207
----------------
 
208
 
 
209
``bzrlib/tests/script.py`` allows users to write tests in a syntax very close to a shell session,
 
210
using a restricted and limited set of commands that should be enough to mimic
 
211
most of the behaviours.
 
212
 
 
213
A script is a set of commands, each command is composed of:
 
214
 
 
215
 * one mandatory command line,
 
216
 * one optional set of input lines to feed the command,
 
217
 * one optional set of output expected lines,
 
218
 * one optional set of error expected lines.
 
219
 
 
220
Input, output and error lines can be specified in any order.
 
221
 
 
222
Except for the expected output, all lines start with a special
 
223
string (based on their origin when used under a Unix shell):
 
224
 
 
225
 * '$ ' for the command,
 
226
 * '<' for input,
 
227
 * nothing for output,
 
228
 * '2>' for errors,
 
229
 
 
230
Comments can be added anywhere, they start with '#' and end with
 
231
the line.
 
232
 
 
233
The execution stops as soon as an expected output or an expected error is not
 
234
matched.
 
235
 
 
236
When no output is specified, any ouput from the command is accepted
 
237
and execution continue.
 
238
 
 
239
If an error occurs and no expected error is specified, the execution stops.
 
240
 
 
241
An error is defined by a returned status different from zero, not by the
 
242
presence of text on the error stream.
 
243
 
 
244
The matching is done on a full string comparison basis unless '...' is used, in
 
245
which case expected output/errors can be less precise.
 
246
 
 
247
Examples:
 
248
 
 
249
The following will succeeds only if 'bzr add' outputs 'adding file'::
 
250
 
 
251
  $ bzr add file
 
252
  >adding file
 
253
 
 
254
If you want the command to succeed for any output, just use::
 
255
 
 
256
  $ bzr add file
 
257
 
 
258
The following will stop with an error::
 
259
 
 
260
  $ bzr not-a-command
 
261
 
 
262
If you want it to succeed, use::
 
263
 
 
264
  $ bzr not-a-command
 
265
  2> bzr: ERROR: unknown command "not-a-command"
 
266
 
 
267
You can use ellipsis (...) to replace any piece of text you don't want to be
 
268
matched exactly::
 
269
 
 
270
  $ bzr branch not-a-branch
 
271
  2>bzr: ERROR: Not a branch...not-a-branch/".
 
272
 
 
273
This can be used to ignore entire lines too::
 
274
 
 
275
  $ cat
 
276
  <first line
 
277
  <second line
 
278
  <third line
 
279
  # And here we explain that surprising fourth line
 
280
  <fourth line
 
281
  <last line
 
282
  >first line
 
283
  >...
 
284
  >last line
 
285
 
 
286
You can check the content of a file with cat::
 
287
 
 
288
  $ cat <file
 
289
  >expected content
 
290
 
 
291
You can also check the existence of a file with cat, the following will fail if
 
292
the file doesn't exist::
 
293
 
 
294
  $ cat file
 
295
 
 
296
The actual use of ScriptRunner within a TestCase looks something like
 
297
this::
 
298
 
 
299
        def test_unshelve_keep(self):
 
300
                # some setup here
 
301
                sr = ScriptRunner()
 
302
                sr.run_script(self, '''
 
303
        $ bzr add file
 
304
        $ bzr shelve --all -m Foo
 
305
        $ bzr shelve --list
 
306
        1: Foo
 
307
        $ bzr unshelve --keep
 
308
        $ bzr shelve --list
 
309
        1: Foo
 
310
        $ cat file
 
311
        contents of file
 
312
        ''')
 
313
 
 
314
 
 
315
 
204
316
.. Effort tests
205
317
.. ~~~~~~~~~~~~
206
318
 
255
367
        The test exists but is known to fail, for example this might be
256
368
        appropriate to raise if you've committed a test for a bug but not
257
369
        the fix for it, or if something works on Unix but not on Windows.
258
 
        
 
370
 
259
371
        Raising this allows you to distinguish these failures from the
260
372
        ones that are not expected to fail.  If the test would fail
261
373
        because of something we don't expect or intend to fix,
265
377
        KnownFailure should be used with care as we don't want a
266
378
        proliferation of quietly broken tests.
267
379
 
 
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
 
 
394
 
268
395
We plan to support three modes for running the test suite to control the
269
396
interpretation of these results.  Strict mode is for use in situations
270
397
like merges to the mainline and releases where we want to make sure that
281
408
UnavailableFeature      fail    pass    pass
282
409
KnownFailure            fail    pass    pass
283
410
======================= ======= ======= ========
284
 
     
 
411
 
285
412
 
286
413
Test feature dependencies
287
414
-------------------------
328
455
``_probe`` and ``feature_name`` methods.  For example::
329
456
 
330
457
    class _SymlinkFeature(Feature):
331
 
    
 
458
 
332
459
        def _probe(self):
333
460
            return osutils.has_symlinks()
334
 
    
 
461
 
335
462
        def feature_name(self):
336
463
            return 'symlinks'
337
 
    
 
464
 
338
465
    SymlinkFeature = _SymlinkFeature()
339
466
 
340
467
 
516
643
 
517
644
Please see bzrlib.branchbuilder for more details.
518
645
 
 
646
If you're going to examine the commit timestamps e.g. in a test for log
 
647
output, you should set the timestamp on the tree, rather than using fuzzy
 
648
matches in the test.
 
649
 
519
650
 
520
651
TreeBuilder
521
652
~~~~~~~~~~~