Merge remote-tracking branch 'cacarrara/doc-mux-inject-v2'

Signed-off-by: NCleber Rosa <crosa@redhat.com>

docs/source/optional_plugins/varianter_yaml_to_mux.rst

@@ -567,3 +567,48 @@ From this example you can see that querying for ``/env/debug`` works only in
 the first variant, but returns nothing in the second variant. Keep this in mind
 and when you use the ``!mux`` flag always query for the pre-mux path,
 ``/env/*`` in this example.
+
+
+Injecting values
+----------------
+
+Beyond the values injected by YAML files specified it's also possible
+inject values directly from command line to the final multiplex tree.
+It's done by the argument  ``--mux-inject``. The format of expected
+value is ``[path:]key:node_value``.
+
+.. warning:: When no path is specified to ``--mux-inject`` the parameter
+   is added under tree root ``/``. For example: running avocado passing
+   ``--mux-inject my_key:my_value`` the parameter can be accessed calling
+   ``self.params.get('my_key')``. If the test writer wants to put the injected
+   value in any other path location, like extending the ``/run`` path, it needs
+   to be informed on avocado run call.  For example: ``--mux-inject
+   /run/:my_key:my_value`` makes possible to access the parameters
+   calling ``self.params.get('my_key', '/run')``
+
+
+A test that gets parameters without a defined path, such as
+``examples/tests/multiplextest.py``::
+
+   os_type = self.params.get('os_type', default='linux')
+
+Running it::
+
+   $ avocado --show=test run -- examples/tests/multiplextest.py  | grep os_type
+   PARAMS (key=os_type, path=*, default=linux) => 'linux'
+
+Now, injecting a value, by default will put it in /, which is not in the
+default list of paths searched for::
+
+   $ avocado --show=test run --mux-inject os_type:myos -- examples/tests/multiplextest.py  | grep os_type
+   PARAMS (key=os_type, path=*, default=linux) => 'linux'
+
+A path that is searched for by default is /run. To set the value to that path use::
+
+   $ avocado --show=test run --mux-inject /run:os_type:myos -- examples/tests/multiplextest.py  | grep os_type
+   PARAMS (key=os_type, path=*, default=linux) => 'myos'
+
+Or, add the / to the list of paths searched for by default::
+
+   $ avocado --show=test run --mux-inject os_type:myos --mux-path / -- examples/tests/multiplextest.py  | grep os_type
+   PARAMS (key=os_type, path=*, default=linux) => 'myos'