← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

Merge bzr.dev to resolve news conflict

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
446
459
            contents of file
447
460
            ''')
448
461
 
 
462
You can also test commands that read user interaction::
 
463
 
 
464
    def test_confirm_action(self):
 
465
        """You can write tests that demonstrate user confirmation"""
 
466
        commands.builtin_command_registry.register(cmd_test_confirm)
 
467
        self.addCleanup(commands.builtin_command_registry.remove, 'test-confirm')
 
468
        self.run_script("""
 
469
            $ bzr test-confirm
 
470
            2>Really do it? [y/n]: 
 
471
            <yes
 
472
            yes
 
473
            """)
 
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
           
449
487
 
450
488
Import tariff tests
451
489
-------------------
699
737
        _test_needs_features = [features.apport]
700
738
 
701
739
 
 
740
Testing deprecated code
 
741
-----------------------
 
742
 
 
743
When code is deprecated, it is still supported for some length of time,
 
744
usually until the next major version. The ``applyDeprecated`` helper
 
745
wraps calls to deprecated code to verify that it is correctly issuing the
 
746
deprecation warning, and also prevents the warnings from being printed
 
747
during test runs.
 
748
 
 
749
Typically patches that apply the ``@deprecated_function`` decorator should
 
750
update the accompanying tests to use the ``applyDeprecated`` wrapper.
 
751
 
 
752
``applyDeprecated`` is defined in ``bzrlib.tests.TestCase``. See the API
 
753
docs for more details.
 
754
 
 
755
 
702
756
Testing exceptions and errors
703
757
-----------------------------
704
758
 
777
831
whether a test should be added for that particular implementation,
778
832
or for all implementations of the interface.
779
833
 
780
 
The multiplication of tests for different implementations is normally
781
 
accomplished by overriding the ``load_tests`` function used to load tests
782
 
from a module.  This function typically loads all the tests, then applies
783
 
a TestProviderAdapter to them, which generates a longer suite containing
784
 
all the test variations.
785
 
 
786
834
See also `Per-implementation tests`_ (above).
787
835
 
788
836
 
789
 
Test scenarios
790
 
--------------
 
837
Test scenarios and variations
 
838
-----------------------------
791
839
 
792
840
Some utilities are provided for generating variations of tests.  This can
793
841
be used for per-implementation tests, or other cases where the same test
798
846
values to which the test should be applied.  The test suite should then
799
847
also provide a list of scenarios in which to run the tests.
800
848
 
801
 
Typically ``multiply_tests_from_modules`` should be called from the test
802
 
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
    variations = 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.
803
867
 
804
868
 
805
869
Test support