← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Jelmer Vernooij
  • Date: 2010-12-20 11:57:14 UTC
  • mto: This revision was merged to the branch mainline in revision 5577.
  • Revision ID: jelmer@samba.org-20101220115714-2ru3hfappjweeg7q
Don't use no-plugins.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/testing.txt
340
340
Shell-like tests
341
341
----------------
342
342
 
343
 
``bzrlib/tests/script.py`` allows users to write tests in a syntax very close to a shell session,
344
 
using a restricted and limited set of commands that should be enough to mimic
345
 
most of the behaviours.
 
343
``bzrlib/tests/script.py`` allows users to write tests in a syntax very
 
344
close to a shell session, using a restricted and limited set of commands
 
345
that should be enough to mimic most of the behaviours.
346
346
 
347
347
A script is a set of commands, each command is composed of:
348
348
 
367
367
The execution stops as soon as an expected output or an expected error is not
368
368
matched.
369
369
 
370
 
When no output is specified, any ouput from the command is accepted
371
 
and execution continue.
 
370
If output occurs and no output is expected, the execution stops and the
 
371
test fails.  If unexpected output occurs on the standard error, then
 
372
execution stops and the test fails.
372
373
 
373
374
If an error occurs and no expected error is specified, the execution stops.
374
375
 
388
389
If you want the command to succeed for any output, just use::
389
390
 
390
391
  $ bzr add file
 
392
  ...
 
393
  2>...
 
394
 
 
395
or use the ``--quiet`` option::
 
396
 
 
397
  $ bzr add -q file
391
398
 
392
399
The following will stop with an error::
393
400
 
427
434
 
428
435
  $ cat file
429
436
 
 
437
You can run files containing shell-like scripts with::
 
438
 
 
439
  $ bzr test-script <script>
 
440
 
 
441
where ``<script>`` is the path to the file containing the shell-like script.
 
442
 
430
443
The actual use of ScriptRunner within a TestCase looks something like
431
444
this::
432
445
 
435
448
    def test_unshelve_keep(self):
436
449
        # some setup here
437
450
        script.run_script(self, '''
438
 
            $ bzr add file
439
 
            $ bzr shelve --all -m Foo
 
451
            $ bzr add -q file
 
452
            $ bzr shelve -q --all -m Foo
440
453
            $ bzr shelve --list
441
454
            1: Foo
442
 
            $ bzr unshelve --keep
 
455
            $ bzr unshelve -q --keep
443
456
            $ bzr shelve --list
444
457
            1: Foo
445
458
            $ cat file
459
472
            yes
460
473
            """)
461
474
 
 
475
To avoid having to specify "-q" for all commands whose output is
 
476
irrelevant, the run_script() method may be passed the keyword argument
 
477
``null_output_matches_anything=True``.  For example::
 
478
 
 
479
    def test_ignoring_null_output(self):
 
480
        self.run_script("""
 
481
            $ bzr init
 
482
            $ bzr ci -m 'first revision' --unchanged
 
483
            $ bzr log --line
 
484
            1: ...
 
485
            """, null_output_matches_anything=True)
 
486
           
 
487
 
462
488
Import tariff tests
463
489
-------------------
464
490
 
805
831
whether a test should be added for that particular implementation,
806
832
or for all implementations of the interface.
807
833
 
808
 
The multiplication of tests for different implementations is normally
809
 
accomplished by overriding the ``load_tests`` function used to load tests
810
 
from a module.  This function typically loads all the tests, then applies
811
 
a TestProviderAdapter to them, which generates a longer suite containing
812
 
all the test variations.
813
 
 
814
834
See also `Per-implementation tests`_ (above).
815
835
 
816
836
 
817
 
Test scenarios
818
 
--------------
 
837
Test scenarios and variations
 
838
-----------------------------
819
839
 
820
840
Some utilities are provided for generating variations of tests.  This can
821
841
be used for per-implementation tests, or other cases where the same test
826
846
values to which the test should be applied.  The test suite should then
827
847
also provide a list of scenarios in which to run the tests.
828
848
 
829
 
Typically ``multiply_tests_from_modules`` should be called from the test
830
 
module's ``load_tests`` function.
 
849
A single *scenario* is defined by a `(name, parameter_dict)` tuple.  The
 
850
short string name is combined with the name of the test method to form the
 
851
test instance name.  The parameter dict is merged into the instance's
 
852
attributes.
 
853
 
 
854
For example::
 
855
 
 
856
    load_tests = load_tests_apply_scenarios
 
857
 
 
858
    class TestCheckout(TestCase):
 
859
 
 
860
        scenarios = multiply_scenarios(
 
861
            VaryByRepositoryFormat(), 
 
862
            VaryByTreeFormat(),
 
863
            )
 
864
 
 
865
The `load_tests` declaration or definition should be near the top of the
 
866
file so its effect can be seen.
831
867
 
832
868
 
833
869
Test support