[IMP] doc: add information on the new populate feature.

* Cmdline interface: how to trigger database population
* Testing: how to implement database population on a given model.
  * autodocumentation of the population methods

+ improve population methods docstrings.

closes odoo/odoo#50596

Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>

2 files changed, 131 insertions, 2 deletions

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index e55b9147d92..71b52bce8bb 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -536,6 +536,10 @@ starting requirements are.
 
 Scaffolding is available via the :command:`odoo-bin scaffold` subcommand.
 
+.. code-block:: console
+
+    $ odoo_bin scaffold my_module /addons/
+
 .. option:: name (required)
 
     the name of the module to create, may munged in various manners to
@@ -551,8 +555,34 @@ Scaffolding is available via the :command:`odoo-bin scaffold` subcommand.
     a template directory, files are passed through jinja2_ then copied to
     the ``destination`` directory
 
+
+This will create module *my_module* in directory */addons/*.
+
+.. _reference/cmdline/populate:
+
+Database Population
+===================
+
+.. program:: odoo-bin populate
+
+Odoo CLI supports database population features. If the feature is
+:ref:`implemented on a given model<reference/testing/populate/methods>`, it allows automatic data
+generation of the model's records to test your modules in databases containing non-trivial amounts of records.
+
 .. code-block:: console
 
-    $ odoo_bin scaffold my_module /addons/
+    $ odoo_bin populate
 
-This will create module *my_module* in directory */addons/*.
+.. option:: --models
+
+    list of models for which the database should be filled
+
+.. option:: --size (small|medium|large)
+
+    population size, the actual records number depends on the model's `_populate_sizes` attribute.
+    The generated records content is specified by the :meth:`~odoo.models._populate_factories` method
+    of a given model (cf. the :file:`populate` folder of modules for further details).
+
+.. seealso::
+
+    :ref:`reference/testing/populate`
diff --git a/doc/reference/testing.rst b/doc/reference/testing.rst
index 55c229fd041..346f369a828 100644
--- a/doc/reference/testing.rst
+++ b/doc/reference/testing.rst
@@ -526,6 +526,105 @@ Two new command line arguments were added since Odoo 13.0 to control this behavi
 :option:`--screenshots <odoo-bin --screenshots>` and :option:`--screencasts <odoo-bin --screencasts>`
 
 
+Performance Testing
+===================
+
+Query counts
+------------
+
+One of the ways to test performance is to measure database queries. Manually, this can be tested with the
+`--log-sql` CLI parameter. If you want to establish the maximum number of queries for an operation,
+you can use the :meth:`~odoo.tests.common.BaseCase.assertQueryCount` method, integrated in Odoo test classes.
+
+.. code-block:: python
+
+    with self.assertQueryCount(11):
+        do_something()
+
+.. _reference/testing/populate:
+
+Database population
+-------------------
+
+Odoo CLI offers a :ref:`database population<reference/cmdline/populate>` feature.
+
+.. code-block:: console
+
+    odoo-bin populate
+
+Instead of the tedious manual, or programmatic, specification of test data,
+one can use this feature to fill a database on demand with the desired number of test data.
+This can be used to detect diverse bugs or performance issues in tested flows.
+
+To specify this feature for a given model, the following methods and attributes can be defined.
+
+.. _reference/testing/populate/methods:
+
+.. currentmodule:: odoo.models
+
+.. autoattribute:: Model._populate_sizes
+.. autoattribute:: Model._populate_dependencies
+.. automethod:: Model._populate
+.. automethod:: Model._populate_factories
+
+.. note::
+
+    You have to define at least :meth:`~odoo.models.Model._populate` or :meth:`~odoo.models.Model._populate_factories`
+    on the model to enable database population.
+
+Example model
+^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    from odoo.tools import populate
+
+    class CustomModel(models.Model)
+        _inherit = "custom.some_model"
+        _populate_sizes = {"small": 100, "medium": 2000, "large": 10000}
+        _populate_dependencies = ["custom.some_other_model"]
+
+        def _populate_factories(self):
+            # Record ids of previously populated models are accessible in the registry
+            some_other_ids = self.env.registry.populated_models["custom.some_other_model"]
+
+            def get_some_field(values=None, random=None, **kwargs):
+                """ Choose a value for some_field depending on other fields values.
+
+                    :param dict values:
+                    :param random: seeded :class:`random.Random` object
+                """
+                field_1 = values['field_1']
+                if field_1 in [value2, value3]:
+                    return random.choice(some_field_values)
+                return False
+
+            return [
+                ("field_1", populate.randomize([value1, value2, value3])),
+                ("field_2", populate.randomize([value_a, value_b], [0.5, 0.5])),
+                ("some_other_id", populate.randomize(some_other_ids)),
+                ("some_field", populate.compute(get_some_field, seed="some_field")),
+                ('active', populate.cartesian([True, False])),
+            ]
+
+        def _populate(self, size):
+            records = super()._populate(size)
+
+            # If you want to update the generated records
+            # E.g setting the parent-child relationships
+            records.do_something()
+
+            return records
+
+Population tools
+^^^^^^^^^^^^^^^^
+
+Multiple population tools are available to easily create
+the needed data generators.
+
+.. automodule:: odoo.tools.populate
+    :members: cartesian, compute, constant, iterate, randint, randomize
+
 .. _qunit: https://qunitjs.com/
 .. _qunit_config.js: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/qunit_config.js#L49
 .. _web.tests_assets: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/views/webclient_templates.xml#L594