← Back to branch summary

~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: 2009-11-17 03:20:35 UTC
  • mfrom: (4792.4.3 456036)
  • Revision ID: pqm@pqm.ubuntu.com-20091117032035-s3sgtlixj1lrminn
(Gordon Tyler) Fix IndexError during 'bzr ignore /' (#456036)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/testing.txt
154
154
    cmd_object.run() method directly. This is a lot faster than
155
155
    subprocesses and generates the same logging output as running it in a
156
156
    subprocess (which invoking the method directly does not).
157
 
 
 
157
 
158
158
 3. Only test the one command in a single test script. Use the bzrlib
159
159
    library when setting up tests and when evaluating the side-effects of
160
160
    the command. We do this so that the library api has continual pressure
173
173
 
174
174
Per-implementation tests are tests that are defined once and then run
175
175
against multiple implementations of an interface.  For example,
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``.
 
176
``test_transport_implementations.py`` defines tests that all Transport
 
177
implementations (local filesystem, HTTP, and so on) must pass.
 
178
 
 
179
They are found in ``bzrlib/tests/*_implementations/test_*.py``,
 
180
``bzrlib/tests/per_*/*.py``, and
 
181
``bzrlib/tests/test_*_implementations.py``.
179
182
 
180
183
These are really a sub-category of unit tests, but an important one.
181
184
 
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
 
 
191
185
 
192
186
Doctests
193
187
~~~~~~~~
204
198
 
205
199
 
206
200
Shell-like tests
207
 
----------------
 
201
~~~~~~~~~~~~~~~~
208
202
 
209
203
``bzrlib/tests/script.py`` allows users to write tests in a syntax very close to a shell session,
210
204
using a restricted and limited set of commands that should be enough to mimic
231
225
the line.
232
226
 
233
227
The execution stops as soon as an expected output or an expected error is not
234
 
matched.
 
228
matched. 
235
229
 
236
230
When no output is specified, any ouput from the command is accepted
237
 
and execution continue.
 
231
and execution continue. 
238
232
 
239
233
If an error occurs and no expected error is specified, the execution stops.
240
234
 
293
287
 
294
288
  $ cat file
295
289
 
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
290
 
315
291
 
316
292
.. Effort tests
367
343
        The test exists but is known to fail, for example this might be
368
344
        appropriate to raise if you've committed a test for a bug but not
369
345
        the fix for it, or if something works on Unix but not on Windows.
370
 
 
 
346
        
371
347
        Raising this allows you to distinguish these failures from the
372
348
        ones that are not expected to fail.  If the test would fail
373
349
        because of something we don't expect or intend to fix,
377
353
        KnownFailure should be used with care as we don't want a
378
354
        proliferation of quietly broken tests.
379
355
 
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
 
 
395
356
We plan to support three modes for running the test suite to control the
396
357
interpretation of these results.  Strict mode is for use in situations
397
358
like merges to the mainline and releases where we want to make sure that
408
369
UnavailableFeature      fail    pass    pass
409
370
KnownFailure            fail    pass    pass
410
371
======================= ======= ======= ========
411
 
 
 
372
     
412
373
 
413
374
Test feature dependencies
414
375
-------------------------
455
416
``_probe`` and ``feature_name`` methods.  For example::
456
417
 
457
418
    class _SymlinkFeature(Feature):
458
 
 
 
419
    
459
420
        def _probe(self):
460
421
            return osutils.has_symlinks()
461
 
 
 
422
    
462
423
        def feature_name(self):
463
424
            return 'symlinks'
464
 
 
 
425
    
465
426
    SymlinkFeature = _SymlinkFeature()
466
427
 
467
428