/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: Jonathan Lange
  • Date: 2009-12-09 09:20:42 UTC
  • mfrom: (4881 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4907.
  • Revision ID: jml@canonical.com-20091209092042-s2zgqcf8f39yzxpj
Merge trunk.

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
201
197
  __ http://docs.python.org/lib/module-doctest.html
202
198
 
203
199
 
 
200
Shell-like tests
 
201
~~~~~~~~~~~~~~~~
 
202
 
 
203
``bzrlib/tests/script.py`` allows users to write tests in a syntax very close to a shell session,
 
204
using a restricted and limited set of commands that should be enough to mimic
 
205
most of the behaviours.
 
206
 
 
207
A script is a set of commands, each command is composed of:
 
208
 
 
209
 * one mandatory command line,
 
210
 * one optional set of input lines to feed the command,
 
211
 * one optional set of output expected lines,
 
212
 * one optional set of error expected lines.
 
213
 
 
214
Input, output and error lines can be specified in any order.
 
215
 
 
216
Except for the expected output, all lines start with a special
 
217
string (based on their origin when used under a Unix shell):
 
218
 
 
219
 * '$ ' for the command,
 
220
 * '<' for input,
 
221
 * nothing for output,
 
222
 * '2>' for errors,
 
223
 
 
224
Comments can be added anywhere, they start with '#' and end with
 
225
the line.
 
226
 
 
227
The execution stops as soon as an expected output or an expected error is not
 
228
matched.
 
229
 
 
230
When no output is specified, any ouput from the command is accepted
 
231
and execution continue.
 
232
 
 
233
If an error occurs and no expected error is specified, the execution stops.
 
234
 
 
235
An error is defined by a returned status different from zero, not by the
 
236
presence of text on the error stream.
 
237
 
 
238
The matching is done on a full string comparison basis unless '...' is used, in
 
239
which case expected output/errors can be less precise.
 
240
 
 
241
Examples:
 
242
 
 
243
The following will succeeds only if 'bzr add' outputs 'adding file'::
 
244
 
 
245
  $ bzr add file
 
246
  >adding file
 
247
 
 
248
If you want the command to succeed for any output, just use::
 
249
 
 
250
  $ bzr add file
 
251
 
 
252
The following will stop with an error::
 
253
 
 
254
  $ bzr not-a-command
 
255
 
 
256
If you want it to succeed, use::
 
257
 
 
258
  $ bzr not-a-command
 
259
  2> bzr: ERROR: unknown command "not-a-command"
 
260
 
 
261
You can use ellipsis (...) to replace any piece of text you don't want to be
 
262
matched exactly::
 
263
 
 
264
  $ bzr branch not-a-branch
 
265
  2>bzr: ERROR: Not a branch...not-a-branch/".
 
266
 
 
267
This can be used to ignore entire lines too::
 
268
 
 
269
  $ cat
 
270
  <first line
 
271
  <second line
 
272
  <third line
 
273
  # And here we explain that surprising fourth line
 
274
  <fourth line
 
275
  <last line
 
276
  >first line
 
277
  >...
 
278
  >last line
 
279
 
 
280
You can check the content of a file with cat::
 
281
 
 
282
  $ cat <file
 
283
  >expected content
 
284
 
 
285
You can also check the existence of a file with cat, the following will fail if
 
286
the file doesn't exist::
 
287
 
 
288
  $ cat file
 
289
 
 
290
 
 
291
 
204
292
.. Effort tests
205
293
.. ~~~~~~~~~~~~
206
294
 
255
343
        The test exists but is known to fail, for example this might be
256
344
        appropriate to raise if you've committed a test for a bug but not
257
345
        the fix for it, or if something works on Unix but not on Windows.
258
 
        
 
346
 
259
347
        Raising this allows you to distinguish these failures from the
260
348
        ones that are not expected to fail.  If the test would fail
261
349
        because of something we don't expect or intend to fix,
281
369
UnavailableFeature      fail    pass    pass
282
370
KnownFailure            fail    pass    pass
283
371
======================= ======= ======= ========
284
 
     
 
372
 
285
373
 
286
374
Test feature dependencies
287
375
-------------------------
328
416
``_probe`` and ``feature_name`` methods.  For example::
329
417
 
330
418
    class _SymlinkFeature(Feature):
331
 
    
 
419
 
332
420
        def _probe(self):
333
421
            return osutils.has_symlinks()
334
 
    
 
422
 
335
423
        def feature_name(self):
336
424
            return 'symlinks'
337
 
    
 
425
 
338
426
    SymlinkFeature = _SymlinkFeature()
339
427
 
340
428