← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Martin
  • Date: 2010-09-05 17:15:46 UTC
  • mto: This revision was merged to the branch mainline in revision 5412.
  • Revision ID: gzlist@googlemail.com-20100905171546-3ggqhogy23fgoxc8
Add check in lazy import ScopeReplacer to ensure it's not trying to replace itself

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/testing.txt
329
329
We make selective use of doctests__.  In general they should provide
330
330
*examples* within the API documentation which can incidentally be tested.  We
331
331
don't try to test every important case using doctests |--| regular Python
332
 
tests are generally a better solution.  That is, we just use doctests to make
333
 
our documentation testable, rather than as a way to make tests. Be aware that
334
 
doctests are not as well isolated as the unit tests, if you need more
335
 
isolation, you're likely want to write unit tests anyway if only to get a
336
 
better control of the test environment.
 
332
tests are generally a better solution.  That is, we just use doctests to
 
333
make our documentation testable, rather than as a way to make tests.
337
334
 
338
335
Most of these are in ``bzrlib/doc/api``.  More additions are welcome.
339
336
 
343
340
Shell-like tests
344
341
----------------
345
342
 
346
 
``bzrlib/tests/script.py`` allows users to write tests in a syntax very
347
 
close to a shell session, using a restricted and limited set of commands
348
 
that should be enough to mimic most of the behaviours.
 
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.
349
346
 
350
347
A script is a set of commands, each command is composed of:
351
348
 
370
367
The execution stops as soon as an expected output or an expected error is not
371
368
matched.
372
369
 
373
 
If output occurs and no output is expected, the execution stops and the
374
 
test fails.  If unexpected output occurs on the standard error, then
375
 
execution stops and the test fails.
 
370
When no output is specified, any ouput from the command is accepted
 
371
and execution continue.
376
372
 
377
373
If an error occurs and no expected error is specified, the execution stops.
378
374
 
392
388
If you want the command to succeed for any output, just use::
393
389
 
394
390
  $ bzr add file
395
 
  ...
396
 
  2>...
397
 
 
398
 
or use the ``--quiet`` option::
399
 
 
400
 
  $ bzr add -q file
401
391
 
402
392
The following will stop with an error::
403
393
 
437
427
 
438
428
  $ cat file
439
429
 
440
 
You can run files containing shell-like scripts with::
441
 
 
442
 
  $ bzr test-script <script>
443
 
 
444
 
where ``<script>`` is the path to the file containing the shell-like script.
445
 
 
446
430
The actual use of ScriptRunner within a TestCase looks something like
447
431
this::
448
432
 
451
435
    def test_unshelve_keep(self):
452
436
        # some setup here
453
437
        script.run_script(self, '''
454
 
            $ bzr add -q file
455
 
            $ bzr shelve -q --all -m Foo
 
438
            $ bzr add file
 
439
            $ bzr shelve --all -m Foo
456
440
            $ bzr shelve --list
457
441
            1: Foo
458
 
            $ bzr unshelve -q --keep
 
442
            $ bzr unshelve --keep
459
443
            $ bzr shelve --list
460
444
            1: Foo
461
445
            $ cat file
462
446
            contents of file
463
447
            ''')
464
448
 
465
 
You can also test commands that read user interaction::
466
 
 
467
 
    def test_confirm_action(self):
468
 
        """You can write tests that demonstrate user confirmation"""
469
 
        commands.builtin_command_registry.register(cmd_test_confirm)
470
 
        self.addCleanup(commands.builtin_command_registry.remove, 'test-confirm')
471
 
        self.run_script("""
472
 
            $ bzr test-confirm
473
 
            2>Really do it? [y/n]: 
474
 
            <yes
475
 
            yes
476
 
            """)
477
 
 
478
 
To avoid having to specify "-q" for all commands whose output is
479
 
irrelevant, the run_script() method may be passed the keyword argument
480
 
``null_output_matches_anything=True``.  For example::
481
 
 
482
 
    def test_ignoring_null_output(self):
483
 
        self.run_script("""
484
 
            $ bzr init
485
 
            $ bzr ci -m 'first revision' --unchanged
486
 
            $ bzr log --line
487
 
            1: ...
488
 
            """, null_output_matches_anything=True)
489
 
           
490
449
 
491
450
Import tariff tests
492
451
-------------------
740
699
        _test_needs_features = [features.apport]
741
700
 
742
701
 
743
 
Testing deprecated code
744
 
-----------------------
745
 
 
746
 
When code is deprecated, it is still supported for some length of time,
747
 
usually until the next major version. The ``applyDeprecated`` helper
748
 
wraps calls to deprecated code to verify that it is correctly issuing the
749
 
deprecation warning, and also prevents the warnings from being printed
750
 
during test runs.
751
 
 
752
 
Typically patches that apply the ``@deprecated_function`` decorator should
753
 
update the accompanying tests to use the ``applyDeprecated`` wrapper.
754
 
 
755
 
``applyDeprecated`` is defined in ``bzrlib.tests.TestCase``. See the API
756
 
docs for more details.
757
 
 
758
 
 
759
702
Testing exceptions and errors
760
703
-----------------------------
761
704
 
834
777
whether a test should be added for that particular implementation,
835
778
or for all implementations of the interface.
836
779
 
 
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
 
837
786
See also `Per-implementation tests`_ (above).
838
787
 
839
788
 
840
 
Test scenarios and variations
841
 
-----------------------------
 
789
Test scenarios
 
790
--------------
842
791
 
843
792
Some utilities are provided for generating variations of tests.  This can
844
793
be used for per-implementation tests, or other cases where the same test
849
798
values to which the test should be applied.  The test suite should then
850
799
also provide a list of scenarios in which to run the tests.
851
800
 
852
 
A single *scenario* is defined by a `(name, parameter_dict)` tuple.  The
853
 
short string name is combined with the name of the test method to form the
854
 
test instance name.  The parameter dict is merged into the instance's
855
 
attributes.
856
 
 
857
 
For example::
858
 
 
859
 
    load_tests = load_tests_apply_scenarios
860
 
 
861
 
    class TestCheckout(TestCase):
862
 
 
863
 
        scenarios = multiply_scenarios(
864
 
            VaryByRepositoryFormat(), 
865
 
            VaryByTreeFormat(),
866
 
            )
867
 
 
868
 
The `load_tests` declaration or definition should be near the top of the
869
 
file so its effect can be seen.
 
801
Typically ``multiply_tests_from_modules`` should be called from the test
 
802
module's ``load_tests`` function.
870
803
 
871
804
 
872
805
Test support
980
913
 
981
914
    self.overrideAttr(osutils, '_cached_user_encoding', 'latin-1')
982
915
 
983
 
Temporarily changing environment variables
984
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
985
 
 
986
 
If yout test needs to temporarily change some environment variable value
987
 
(which generally means you want it restored at the end), you can use::
988
 
 
989
 
    self.overrideEnv('BZR_ENV_VAR', 'new_value')
990
 
 
991
 
If you want to remove a variable from the environment, you should use the
992
 
special ``None`` value::
993
 
 
994
 
    self.overrideEnv('PATH', None)
995
 
 
996
 
If you add a new feature which depends on a new environment variable, make
997
 
sure it behaves properly when this variable is not defined (if applicable) and
998
 
if you need to enforce a specific default value, check the
999
 
``TestCase._cleanEnvironment`` in ``bzrlib.tests.__init__.py`` which defines a
1000
 
proper set of values for all tests.
1001
 
 
1002
916
Cleaning up
1003
917
~~~~~~~~~~~
1004
918