/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Jelmer Vernooij
  • Date: 2017-05-21 18:10:28 UTC
  • mto: This revision was merged to the branch mainline in revision 6623.
  • Revision ID: jelmer@jelmer.uk-20170521181028-zn04pdfw0od9hfj3
Rename brzlib => breezy.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/testing.txt
98
98
specified string. It will also avoid loading the other tests and as a
99
99
consequence starts running your tests quicker::
100
100
 
101
 
  ./brz selftest --starting-with brzlib.blackbox
 
101
  ./brz selftest --starting-with breezy.blackbox
102
102
 
103
103
This option can be combined with all the other selftest options including
104
104
--load-list. The later is rarely used but allows to run a subset of a list of
229
229
Where should I put a new test?
230
230
------------------------------
231
231
 
232
 
brzlib's tests are organised by the type of test.  Most of the tests in
 
232
breezy's tests are organised by the type of test.  Most of the tests in
233
233
brz's test suite belong to one of these categories:
234
234
 
235
235
 - Unit tests
237
237
 - Per-implementation tests
238
238
 - Doctests
239
239
 
240
 
A quick description of these test types and where they belong in brzlib's
 
240
A quick description of these test types and where they belong in breezy's
241
241
source follows.  Not all tests fall neatly into one of these categories;
242
242
in those cases use your judgement.
243
243
 
250
250
as possible.  Each unit test is generally fairly short and runs very
251
251
quickly.
252
252
 
253
 
They are found in ``brzlib/tests/test_*.py``.  So in general tests should
 
253
They are found in ``breezy/tests/test_*.py``.  So in general tests should
254
254
be placed in a file named test_FOO.py where FOO is the logical thing under
255
255
test.
256
256
 
257
 
For example, tests for merge3 in brzlib belong in brzlib/tests/test_merge3.py.
258
 
See brzlib/tests/test_sampler.py for a template test script.
 
257
For example, tests for merge3 in breezy belong in breezy/tests/test_merge3.py.
 
258
See breezy/tests/test_sampler.py for a template test script.
259
259
 
260
260
 
261
261
Blackbox (UI) tests
266
266
option, then you should be writing a UI test.  If you are both adding UI
267
267
functionality and library functionality, you will want to write tests for
268
268
both the UI and the core behaviours.  We call UI tests 'blackbox' tests
269
 
and they belong in ``brzlib/tests/blackbox/*.py``.
 
269
and they belong in ``breezy/tests/blackbox/*.py``.
270
270
 
271
271
When writing blackbox tests please honour the following conventions:
272
272
 
273
273
 1. Place the tests for the command 'name' in
274
 
    brzlib/tests/blackbox/test_name.py. This makes it easy for developers
 
274
    breezy/tests/blackbox/test_name.py. This makes it easy for developers
275
275
    to locate the test script for a faulty command.
276
276
 
277
277
 2. Use the 'self.run_brz("name")' utility function to invoke the command
280
280
    subprocesses and generates the same logging output as running it in a
281
281
    subprocess (which invoking the method directly does not).
282
282
 
283
 
 3. Only test the one command in a single test script. Use the brzlib
 
283
 3. Only test the one command in a single test script. Use the breezy
284
284
    library when setting up tests and when evaluating the side-effects of
285
285
    the command. We do this so that the library api has continual pressure
286
286
    on it to be as functional as the command line in a simple manner, and
300
300
against multiple implementations of an interface.  For example,
301
301
``per_transport.py`` defines tests that all Transport implementations
302
302
(local filesystem, HTTP, and so on) must pass. They are found in
303
 
``brzlib/tests/per_*/*.py``, and ``brzlib/tests/per_*.py``.
 
303
``breezy/tests/per_*/*.py``, and ``breezy/tests/per_*.py``.
304
304
 
305
305
These are really a sub-category of unit tests, but an important one.
306
306
 
307
307
Along the same lines are tests for extension modules. We generally have
308
308
both a pure-python and a compiled implementation for each module. As such,
309
309
we want to run the same tests against both implementations. These can
310
 
generally be found in ``brzlib/tests/*__*.py`` since extension modules are
 
310
generally be found in ``breezy/tests/*__*.py`` since extension modules are
311
311
usually prefixed with an underscore. Since there are only two
312
312
implementations, we have a helper function
313
 
``brzlib.tests.permute_for_extension``, which can simplify the
 
313
``breezy.tests.permute_for_extension``, which can simplify the
314
314
``load_tests`` implementation.
315
315
 
316
316
 
326
326
isolation, you're likely want to write unit tests anyway if only to get a
327
327
better control of the test environment.
328
328
 
329
 
Most of these are in ``brzlib/doc/api``.  More additions are welcome.
 
329
Most of these are in ``breezy/doc/api``.  More additions are welcome.
330
330
 
331
331
  __ http://docs.python.org/lib/module-doctest.html
332
332
 
333
333
There is an `assertDoctestExampleMatches` method in
334
 
`brzlib.tests.TestCase` that allows you to match against doctest-style
 
334
`breezy.tests.TestCase` that allows you to match against doctest-style
335
335
string templates (including ``...`` to skip sections) from regular Python
336
336
tests.
337
337
 
339
339
Shell-like tests
340
340
----------------
341
341
 
342
 
``brzlib/tests/script.py`` allows users to write tests in a syntax very
 
342
``breezy/tests/script.py`` allows users to write tests in a syntax very
343
343
close to a shell session, using a restricted and limited set of commands
344
344
that should be enough to mimic most of the behaviours.
345
345
 
442
442
The actual use of ScriptRunner within a TestCase looks something like
443
443
this::
444
444
 
445
 
    from brzlib.tests import script
 
445
    from breezy.tests import script
446
446
 
447
447
    def test_unshelve_keep(self):
448
448
        # some setup here
487
487
Import tariff tests
488
488
-------------------
489
489
 
490
 
`brzlib.tests.test_import_tariff` has some tests that measure how many
 
490
`breezy.tests.test_import_tariff` has some tests that measure how many
491
491
Python modules are loaded to run some representative commands.
492
492
 
493
493
We want to avoid loading code unnecessarily, for reasons including:
545
545
a hook that is called when a write lock is: acquired, released or broken.
546
546
(Read locks also exist, they cannot be discovered in this way.)
547
547
 
548
 
A hook can be installed by calling brzlib.lock.Lock.hooks.install_named_hook.
 
548
A hook can be installed by calling breezy.lock.Lock.hooks.install_named_hook.
549
549
The three valid hooks are: `lock_acquired`, `lock_released` and `lock_broken`.
550
550
 
551
551
Example::
572
572
 
573
573
    self.assertEndsWith(locks_acquired[0].lock_url, "/checkout/lock")
574
574
 
575
 
See brzlib/tests/commands/test_revert.py for an example of how to use this for
 
575
See breezy/tests/commands/test_revert.py for an example of how to use this for
576
576
testing locks.
577
577
 
578
578
 
686
686
actually instances not classses they're now given instance-style names
687
687
like ``apport``.
688
688
 
689
 
Features already defined in ``brzlib.tests`` and ``brzlib.tests.features``
 
689
Features already defined in ``breezy.tests`` and ``breezy.tests.features``
690
690
include:
691
691
 
692
692
 - apport
707
707
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
708
708
 
709
709
New features for use with ``_test_needs_features`` or ``requireFeature``
710
 
are defined by subclassing ``brzlib.tests.Feature`` and overriding the
 
710
are defined by subclassing ``breezy.tests.Feature`` and overriding the
711
711
``_probe`` and ``feature_name`` methods.  For example::
712
712
 
713
713
    class _SymlinkFeature(Feature):
723
723
A helper for handling running tests based on whether a python
724
724
module is available. This can handle 3rd-party dependencies (is
725
725
``paramiko`` available?) as well as stdlib (``termios``) or
726
 
extension modules (``brzlib._groupcompress_pyx``). You create a
 
726
extension modules (``breezy._groupcompress_pyx``). You create a
727
727
new feature instance with::
728
728
 
729
 
    # in brzlib/tests/features.py
 
729
    # in breezy/tests/features.py
730
730
    apport = tests.ModuleAvailableFeature('apport')
731
731
 
732
732
 
733
 
    # then in brzlib/tests/test_apport.py
 
733
    # then in breezy/tests/test_apport.py
734
734
    class TestApportReporting(TestCaseInTempDir):
735
735
 
736
736
        _test_needs_features = [features.apport]
764
764
Typically patches that apply the ``@deprecated_function`` decorator should
765
765
update the accompanying tests to use the ``applyDeprecated`` wrapper.
766
766
 
767
 
``applyDeprecated`` is defined in ``brzlib.tests.TestCase``. See the API
 
767
``applyDeprecated`` is defined in ``breezy.tests.TestCase``. See the API
768
768
docs for more details.
769
769
 
770
770
 
830
830
fulfils the interface requirements.  For example, every Transport should
831
831
support the ``has()`` and ``get()`` and ``clone()`` methods.  We have a
832
832
sub-suite of tests in ``test_transport_implementations``.  (Most
833
 
per-implementation tests are in submodules of ``brzlib.tests``, but not
 
833
per-implementation tests are in submodules of ``breezy.tests``, but not
834
834
the transport tests at the moment.)
835
835
 
836
836
These tests are repeated for each registered Transport, by generating a
892
892
TestCase and its subclasses
893
893
~~~~~~~~~~~~~~~~~~~~~~~~~~~
894
894
 
895
 
The ``brzlib.tests`` module defines many TestCase classes to help you
 
895
The ``breezy.tests`` module defines many TestCase classes to help you
896
896
write your tests.
897
897
 
898
898
TestCase
905
905
    interfere with your test.  All tests should use this base class
906
906
    (whether directly or via a subclass).  Note that we are trying not to
907
907
    add more assertions at this point, and instead to build up a library
908
 
    of ``brzlib.tests.matchers``.
 
908
    of ``breezy.tests.matchers``.
909
909
 
910
910
TestCaseWithMemoryTransport
911
911
    Extends TestCase and adds methods like ``get_transport``,
957
957
testing how we work with disk objects should, of course, use a real
958
958
``WorkingTree``.
959
959
 
960
 
Please see brzlib.branchbuilder for more details.
 
960
Please see breezy.branchbuilder for more details.
961
961
 
962
962
If you're going to examine the commit timestamps e.g. in a test for log
963
963
output, you should set the timestamp on the tree, rather than using fuzzy
981
981
method of ``TestCaseWithMemoryTransport``) or ``make_branch_and_tree`` (a
982
982
method of ``TestCaseWithTransport``).
983
983
 
984
 
Please see brzlib.treebuilder for more details.
 
984
Please see breezy.treebuilder for more details.
985
985
 
986
986
PreviewTree
987
987
~~~~~~~~~~~
1058
1058
If you add a new feature which depends on a new environment variable, make
1059
1059
sure it behaves properly when this variable is not defined (if applicable) and
1060
1060
if you need to enforce a specific default value, check the
1061
 
``TestCase._cleanEnvironment`` in ``brzlib.tests.__init__.py`` which defines a
 
1061
``TestCase._cleanEnvironment`` in ``breezy.tests.__init__.py`` which defines a
1062
1062
proper set of values for all tests.
1063
1063
 
1064
1064
Cleaning up
1070
1070
fails, later cleanups are still run.
1071
1071
 
1072
1072
(The same facility is available outside of tests through
1073
 
``brzlib.cleanup``.)
 
1073
``breezy.cleanup``.)
1074
1074
 
1075
1075
 
1076
1076
Manual testing