[DOC] tours

closes odoo/documentation#11553

X-original-commit: b66cad62fd
Signed-off-by: Bastien Pierre (ipb) <ipb@odoo.com>

content/developer/reference/backend/testing.rst

@@ -578,6 +578,8 @@ You can then:
    - :ref:`Assets Bundle <reference/assets_bundle>`
    - :ref:`testing/python`
 
+.. _testing/javascript/test:
+
 Javascript
 ~~~~~~~~~~
 
@@ -588,7 +590,6 @@ Javascript
       import tour from 'web_tour.tour';
       tour.register('rental_product_configurator_tour', {
           url: '/web',  // Here, you can specify any other starting url
-          test: true,
       }, [
           // Your sequence of steps
       ]);
@@ -730,14 +731,96 @@ To start a tour from a python test, make the class inherit from
 
    def test_your_test(self):
        # Optional Setup
-       self.start_tour("/web", 'your_module.your_tour_name', login="admin")
+       self.start_tour("/web", "your_tour_name", login="admin")
        # Optional verifications
 
+Writing an onboarding tour
+--------------------------
+
+Structure
+~~~~~~~~~
+
+To write an onboarding tour for `your_module`, start with creating the required files:
+
+.. code-block:: text
+
+    your_module
+    ├── ...
+    ├── data
+    |   └── your_tour.xml
+    ├── static/src/js/tours/your_tour.js
+    └── __manifest__.py
+
+You can then update :file:`__manifest__.py` to add :file:`your_tour.js` in the assets and :file:`your_tour.xml` in the data.
+
+  .. code-block:: python
+
+     'data': [
+        'data/your_tour.xml',
+     ],
+     'assets': {
+         'web.assets_backend': [
+             'your_module/static/src/js/tours/your_tour.js',
+         ],
+     },
+
+Javascript
+~~~~~~~~~~
+
+The javascript part is the same as for :ref: `the test tour <testing/javascript/test>`.
+
+XML
+~~~
+
+When you have your tour in the javascript registry, you can create a record `web_tour.tour` in the xml, like that:
+
+  .. code-block:: xml
+
+      <?xml version="1.0" encoding="utf-8"?>
+      <odoo>
+          <record id="your_tour" model="web_tour.tour">
+              <field name="name">your_tour</field>
+              <field name="sequence">10</field>
+              <field name="rainbow_man_message">Congrats, that was a great tour</field>
+          </record>
+      </odoo>
+
+- `name`: Required, the name must be the same as the one in the
+  javascript registry.
+- `sequence`: Optional; determines the order to execute the
+  onboarding tours. Defaults to 1000.
+- `url`: Optional; the url where to start the tour. If ``url`` is ``False``,
+  take the url from the registry. Defaults to "/odoo".
+- `rainbow_man_message`: Optional; will show the message in the
+  rainbow man effect at the completion of the tour. If ``rainbow_man_message`` is ``False``,
+  there is no rainbow effect. Defaults to ``<b>Good job!</b> You went through all steps of this tour.``
+
+Running onboarding tours
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+They can all be started in their sequence order by toggling the :guilabel:`Onboarding` option in the user menu.
+You can run specific onboarding tours by going to the :menuselection:`Settings --> Technical --> User Interface --> Tours`
+and clicking on :guilabel:`Onboarding` or :guilabel:`Testing`.
+
+- **Onboarding**: will execute the tour in interactive mode. That means the tour will show what to do and
+  wait for interactions from the user.
+- **Testing**: will execute the tour automatically. That means the tour will be executing all the step in
+  front of the user.
+
+Tour recorder
+~~~~~~~~~~~~~
+
+You can also create tours easily with the tour recorder. To do so, click on :guilabel:`Record` on the
+onboarding tours view. When started, this tool will record all your interactions in Odoo.
+
+The created tours are flagged in the onboarding tours view as **Custom**. These tours can also
+be exported to a javascript file, ready to be put in your module.
+
 Debugging tips
 --------------
 
-Observing tours in a browser
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Observing test tours in a browser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are three ways with different tradeoffs:
 
@@ -748,7 +831,7 @@ When running a tour locally via the test suite, the ``watch=True``
 parameter can be added to the ``browser_js`` or ``start_tour``
 call::
 
-    self.start_tour("/web", code, watch=True)
+    self.start_tour("/web", "your_tour_name", watch=True)
 
 This will automatically open a Chrome window with the tour being
 run inside it.
@@ -768,7 +851,7 @@ When running a tour locally via the test suite, the ``debug=True``
 parameter can be added to the ``browser_js`` or ``start_tour``
 call::
 
-    self.start_tour("/web", code, debug=True)
+    self.start_tour("/web", "your_tour_name", debug=True)
 
 This will automatically open a fullscreen Chrome window with opened
 devtools and a debugger breakpoint set at the start of the tour. The tour
@@ -785,19 +868,15 @@ debugger stops on the exception.
 Run via browser
 ***************
 
-Tours can also be launched via the browser UI, either by calling
+Test tours can also be launched via the browser UI by calling
 
 .. code-block:: javascript
 
-    odoo.startTour(tour_name);
+    odoo.startTour("tour_name");
 
 in the javascript console, or by enabling :ref:`tests mode
 <frontend/framework/tests_debug_mode>` by setting ``?debug=tests`` in
-the URL, then selecting **Start Tour** in the debug menu and picking a
-tour:
-
-.. image:: testing/tours.png
-   :align: center
+the URL.
 
 **Advantages**
   - easier to run