doc/05_test_framework.rst

   1 .. _test-framework:
   2
   3 Test framework
   4 ==============
   5
   6 In addition to the YAML-based tests, OpenERP uses the unittest2_ testing
   7 framework to test both the core ``openerp`` package and its addons. For the
   8 core and each addons, tests are divided between three (overlapping) sets:
   9
  10 1. A test suite that comprises all the tests that can be run right after the
  11    addons is installed (or, for the core, right after a database is created).
  12    That suite is called ``fast_suite`` and must contain only tests that can be run
  13    frequently. Actually most of the tests should be considered fast enough to be
  14    included in that ``fast_suite`` list and only tests that take a long time to run
  15    (e.g. more than a minute) should not be listed. Those long tests should come up
  16    pretty rarely.
  17
  18 2. A test suite called ``checks`` provides sanity checks. These tests are
  19    invariants that must be full-filled at any time. They are expected to always
  20    pass: obviously they must pass right after the module is installed (i.e. just
  21    like the ``fast_suite`` tests), but they must also pass after any other module is
  22    installed, after a migration, or even after the database was put in production
  23    for a few months.
  24
  25 3. The third suite is made of all the tests: those provided by the two above
  26    suites, but also tests that are not explicitely listed in ``fast_suite`` or
  27    ``checks``. They are not explicitely listed anywhere and are discovered
  28    automatically.
  29
  30 As the sanity checks provide stronger guarantees about the code and database
  31 structure, new tests must be added to the ``checks`` suite whenever it is
  32 possible. Said with other words: one should try to avoid writing tests that
  33 assume a freshly installed/unaltered module or database.
  34
  35 It is possible to have tests that are not listed in ``fast_suite`` or
  36 ``checks``.  This is useful if a test takes a lot of time. By default, when
  37 using the testing infrastructure, tests should run fast enough so that people
  38 can use them frequently. One can also use that possiblity for tests that
  39 require some complex setup before they can be successfuly run.
  40
  41 As a rule of thumb when writing a new test, try to add it to the ``checks``
  42 suite. If it really needs that the module it belongs to is freshly installed,
  43 add it to ``fast_suite``. Finally, if it can not be run in an acceptable time
  44 frame, don't add it to any explicit list.
  45
  46 Writing tests
  47 -------------
  48
  49 The tests must be developed under ``<addons-name>.tests`` (or ``openerp.tests``
  50 for the core).  For instance, with respect to the tests, a module ``foo``
  51 should be organized as follow::
  52
  53   foo/
  54     __init__.py # does not import .tests
  55     tests/
  56       __init__.py # import some of the tests sub-modules, and
  57                   # list them in fast_suite or checks
  58       test_bar.py # contains unittest2 classes
  59       test_baz.py # idem
  60       ... and so on ...
  61
  62 The two explicit lists of tests are thus the variables ``foo.tests.fast_suite``
  63 and ``foo.tests.checks``. As an example, you can take a look at the
  64 ``openerp.tests`` module (which follows exactly the same conventions even if it
  65 is not an addons).
  66
  67 Note that the ``fast_suite`` and ``checks`` variables are really lists of
  68 module objects. They could be directly unittest2 suite objects if necessary in
  69 the future.
  70
  71 Running the tests
  72 -----------------
  73
  74 To run the tests (see :ref:`above <test-framework>` to learn how tests are
  75 organized), the simplest way is to use the ``oe`` command (provided by the
  76 ``openerp-command`` project).
  77
  78 ::
  79
  80   > oe run-tests # will run all the fast_suite tests
  81   > oe run-tests -m openerp # will run all the fast_suite tests defined in `openerp.tests`
  82   > oe run-tests -m sale # will run all the fast_suite tests defined in `openerp.addons.sale.tests`
  83   > oe run-tests -m foo.test_bar # will run the tests defined in `openerp.addons.foo.tests.test_bar`
  84
  85 In addition to the above possibilities, when invoked with a non-existing module
  86 (or module.sub-module) name, oe will reply with a list of available test
  87 sub-modules.
  88
  89 Depending on the unittest2_ class that is used to write the tests (see
  90 :mod:`openerp.tests.common` for some helper classes that you can re-use), a
  91 database may be created before the test is run, and the module providing the
  92 test will be installed on that database.
  93
  94 Because creating a database, installing modules, and then dropping it is
  95 expensive, it is possible to interleave the run of the ``fast_suite`` tests
  96 with the initialization of a new database: the dabase is created, and after
  97 each requested module is installed, its fast_suite tests are run. The database
  98 is thus created and dropped (and the modules installed) only once.
  99
 100 .. _unittest2: http://pypi.python.org/pypi/unittest2
 101
 102 TestCase subclasses
 103 -------------------
 104
 105 .. automodule:: openerp.tests.common
 106    :members:
 107
 108 .. note::
 109
 110     The `setUp` and `tearDown` methods are not part of the tests. Uncaught
 111     exceptions in those methods are errors, not test failures. In particular,
 112     a failing `setUp` will not be followed by a `tearDown` causing any
 113     allocated resource in the `setUp` to not be released by the `tearDown`.
 114
 115     In the :py:class:`openerp.tests.common.TransactionCase` and
 116     :py:class:`openerp.tests.common.SingleTransactionCase`, this means the
 117     test suite can hang because of unclosed cursors.