← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: John Arbash Meinel
  • Date: 2010-09-29 20:56:18 UTC
  • mto: This revision was merged to the branch mainline in revision 5452.
  • Revision ID: john@arbash-meinel.com-20100929205618-qlldxw4ykwt5511n
Move the new NEWS entry to the appropriate section.

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
475
459
            yes
476
460
            """)
477
461
 
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
 
 
491
462
Import tariff tests
492
463
-------------------
493
464
 
834
805
whether a test should be added for that particular implementation,
835
806
or for all implementations of the interface.
836
807
 
 
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
 
837
814
See also `Per-implementation tests`_ (above).
838
815
 
839
816
 
840
 
Test scenarios and variations
841
 
-----------------------------
 
817
Test scenarios
 
818
--------------
842
819
 
843
820
Some utilities are provided for generating variations of tests.  This can
844
821
be used for per-implementation tests, or other cases where the same test
849
826
values to which the test should be applied.  The test suite should then
850
827
also provide a list of scenarios in which to run the tests.
851
828
 
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.
 
829
Typically ``multiply_tests_from_modules`` should be called from the test
 
830
module's ``load_tests`` function.
870
831
 
871
832
 
872
833
Test support
980
941
 
981
942
    self.overrideAttr(osutils, '_cached_user_encoding', 'latin-1')
982
943
 
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
944
Cleaning up
1003
945
~~~~~~~~~~~
1004
946