From 23d840ddce353b9771415a17e6cd4ea73cbb28a5 Mon Sep 17 00:00:00 2001 From: Christophe Monniez Date: Fri, 20 Jul 2018 08:17:21 +0200 Subject: [DOC] cmdline,testing: add documentation for test-tags Closes #25789 --- doc/reference/cmdline.rst | 4 ++ doc/reference/testing.rst | 145 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 148 insertions(+), 1 deletion(-) (limited to 'doc/reference') diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst index 058eac51ddd..7ef31c42701 100644 --- a/doc/reference/cmdline.rst +++ b/doc/reference/cmdline.rst @@ -113,6 +113,10 @@ Running the server runs tests after installing modules +.. option:: --test-tags 'tag_1,tag_2,...,-tag_n' + + select the tests to run by using tags. + .. option:: --dev * ``all``: all the features below are activated diff --git a/doc/reference/testing.rst b/doc/reference/testing.rst index e25e8d31433..d14b3c25838 100644 --- a/doc/reference/testing.rst +++ b/doc/reference/testing.rst @@ -64,6 +64,8 @@ related to testing Odoo content (modules, mainly): .. autoclass:: odoo.tests.common.HttpCase :members: browse_ref, ref, url_open, phantom_js +.. autofunction:: odoo.tests.common.tagged + By default, tests are run once right after the corresponding module has been installed. Test cases can also be configured to run after all modules have been installed, and not run right after the module installation: @@ -111,6 +113,147 @@ supported. .. _unittest documentation: https://docs.python.org/2/library/unittest.html +Test selection +-------------- + +In Odoo, Python tests can be tagged to facilitate the test selection when +running tests. + +Subclasses of :class:`odoo.tests.common.BaseCase` (usually through +:class:`~odoo.tests.common.TransactionCase`, +:class:`~odoo.tests.common.SavepointCase` or +:class:`~odoo.tests.common.HttpCase`) are automatically tagged with +``standard``, ``at_install`` and their source module's name by default. + +Invocation +^^^^^^^^^^ + +:option:`--test-tags ` can be used to select/filter tests +to run on the command-line. + +This option defaults to ``+standard`` meaning tests tagged ``standard`` +(explicitly or implicitly) will be run by default when starting Odoo +with :option:`--test-enable `. + +When writing tests, the :func:`~odoo.tests.common.tagged` decorator can be +used on **test classes** to add or remove tags. + +The decorator's arguments are tag names, as strings. + +.. danger:: :func:`~odoo.tests.common.tagged` is a class decorator, it has no + effect on functions or methods + +Tags can be prefixed with the minus (``-``) sign, to *remove* them instead of +add or select them e.g. if you don't want your test to be executed by +default you can remove the ``standard`` tag: + +.. code-block:: python + + from odoo.tests import TransactionCase, tagged + + @tagged('-standard', 'nice') + class NiceTest(TransactionCase): + ... + +This test will not be selected by default, to run it the relevant tag will +have to be selected explicitely: + +.. code-block:: console + + $ odoo-bin --test-enable --test-tags nice + +Note that only the tests tagged ``nice`` are going to be executed. To run +*both* ``nice`` and ``standard`` tests, provide multiple values to +:option:`--test-tags `: on the command-line, values +are *additive* (you're selecting all tests with *any* of the specified tags) + +.. code-block:: console + + $ odoo-bin --test-enable --test-tags nice,standard + +The config switch parameter also accepts the ``+`` and ``-`` prefixes. The +``+`` prefix is implied and therefore, totaly optional. The ``-`` (minus) +prefix is made to deselect tests tagged with the prefixed tags, even if they +are selected by other specified tags e.g. if there are ``standard`` tests which +are also tagged as ``slow`` you can run all standard tests *except* the slow +ones: + +.. code-block:: console + + $ odoo-bin --test-enable --test-tags 'standard,-slow' + +When you write a test that does not inherit from the +:class:`~odoo.tests.common.BaseCase`, this test will not have the default tags, +you have to add them explicitely to have the test included in the default test +suite. This is a common issue when using a simple ``unittest.TestCase`` as +they're not going to get run: + +.. code-block:: python + + import unittest + from odoo.tests import tagged + + @tagged('standard', 'at_install') + class SmallTest(unittest.TestCase): + ... + +Special tags +^^^^^^^^^^^^ + +- ``standard``: All Odoo tests that inherit from + :class:`~odoo.tests.common.BaseCase` are implicitely tagged standard. + :option:`--test-tags ` also defaults to ``standard``. + + That means untagged test will be executed by default when tests are enabled. +- ``at_install``: Means that the test will be executed right after the module + installation and before other modules are installed. This is a default + implicit tag. +- ``post_install``: Means that the test will be executed after all the modules + are installed. This is what you want for HttpCase tests most of the time. + + Note that this is *not exclusive* with ``at_install``, however since you + will generally not want both ``post_install`` is usually paired with + ``-at_install`` when tagging a test class. +- *module_name*: Odoo tests classes extending + :class:`~odoo.tests.common.BaseCase` are implicitely tagged with the + technical name of their module. This allows easily selecting or excluding + specific modules when testing e.g. if you want to only run tests from + ``stock_account``: + + .. code-block:: console + + $ odoo-bin --test-enable --test-tags stock_account + +Examples +^^^^^^^^ + +.. important:: + + Tests will be executed only in the installed or updated modules. So + modules have to be selected with the :option:`-u ` or + :option:`-i ` switches. For simplicity, those switches are + not specified in the examples below. + +Run only the tests from the sale module: + +.. code-block:: console + + $ odoo-bin --test-enable --test-tags sale + +Run the tests from the sale module but not the ones tagged as slow: + +.. code-block:: console + + $ odoo-bin --test-enable --test-tags 'sale,-slow' + +Run only the tests from stock or tagged as slow: + +.. code-block:: console + + $ odoo-bin --test-enable --test-tags '-standard, slow, stock' + +.. note:: ``-standard`` is implicit (not required), and present for clarity + Testing JS code =============== @@ -153,4 +296,4 @@ that the web client and the server work together. In order to do that, we can write another kind of test: tours. A tour is a mini scenario of some interesting business flow. It explains a sequence of steps that should be followed. The test runner will then create a phantom_js browser, point it to the proper url -and simulate the click and inputs, according to the scenario. \ No newline at end of file +and simulate the click and inputs, according to the scenario. -- cgit v1.2.3