avocado: Replace `--multiplex` with `--mux-yaml`

Recently we created separate `yaml2mux` plugin, which keeps using the
`--multiplex` argument. The connection between yaml2mux and multiplex is
not really obvious and the separation was meant to bring the order to
the avocado params system. This is another step which replaces the
`--multiplex|-m` with `--mux-yaml|-m` and makes it more obvious that
it's related to `yaml` files and it's also related to `multiplexation`.

You might notice that the old `-m` was kept. It's very convenient and
also allows coexisting of old and new versions (useful eg. in remote
executions).
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

avocado/core/remote/runner.py

@@ -183,7 +183,7 @@ class RemoteTestRunner(TestRunner):
                      for mux_file in getattr(self.job.args,
                                              'multiplex') or []]
         if mux_files:
-            extra_params.append("--multiplex %s" % " ".join(mux_files))
+            extra_params.append("-m %s" % " ".join(mux_files))
 
         if getattr(self.job.args, "dry_run", False):
             extra_params.append("--dry-run")

avocado/plugins/yaml_to_mux.py

@@ -13,6 +13,7 @@
 # Author: Lukas Doktor <ldoktor@redhat.com>
 """Multiplexer plugin to parse yaml files to params"""
 
+import logging
 import os
 import re
 import sys
@@ -239,19 +240,34 @@ class YamlToMux(CLI):
             if subparser is None:
                 continue
             mux = subparser.add_argument_group("yaml to mux options")
-            mux.add_argument("-m", "--multiplex", nargs='*', dest="multiplex",
+            mux.add_argument("-m", "--mux-yaml", nargs='*', metavar="FILE",
+                             help="Location of one or more Avocado"
+                             " multiplex (.yaml) FILE(s) (order dependent)")
+            mux.add_argument("--multiplex", nargs='*',
                              default=None, metavar="FILE",
-                             help="Location of one or more Avocado multiplex "
-                             "(.yaml) FILE(s) (order dependent)")
+                             help="DEPRECATED: Location of one or more Avocado"
+                             " multiplex (.yaml) FILE(s) (order dependent)")
 
     def run(self, args):
         # Merge the multiplex
+        multiplex_files = getattr(args, "mux_yaml", None)
+        if multiplex_files:
+            debug = getattr(args, "mux_debug", False)
+            try:
+                args.mux.data_merge(create_from_yaml(multiplex_files, debug))
+            except IOError as details:
+                logging.getLogger("avocado.app").error(details.strerror)
+                sys.exit(exit_codes.AVOCADO_JOB_FAIL)
+
+        # Deprecated --multiplex option
         multiplex_files = getattr(args, "multiplex", None)
         if multiplex_files:
+            msg = ("The use of `--multiplex` is deprecated, use `--mux-yaml` "
+                   "instead.")
+            logging.getLogger("avocado.test").warning(msg)
             debug = getattr(args, "mux_debug", False)
             try:
                 args.mux.data_merge(create_from_yaml(multiplex_files, debug))
             except IOError as details:
-                import logging
                 logging.getLogger("avocado.app").error(details.strerror)
                 sys.exit(exit_codes.AVOCADO_JOB_FAIL)

docs/source/DebuggingWithGDB.rst

@@ -69,7 +69,7 @@ place, the test notifies you and you can investigate the problem. This is
 demonstrated in ``examples/tests/doublefree_nasty.py`` test. To unveil the
 power of Avocado, run this test using::
 
-    avocado run --gdb-run-bin=doublefree: examples/tests/doublefree_nasty.py --gdb-prerun-commands examples/tests/doublefree_nasty.py.data/gdb_pre --multiplex examples/tests/doublefree_nasty.py.data/iterations.yaml
+    avocado run --gdb-run-bin=doublefree: examples/tests/doublefree_nasty.py --gdb-prerun-commands examples/tests/doublefree_nasty.py.data/gdb_pre --mux-yaml examples/tests/doublefree_nasty.py.data/iterations.yaml
 
 which executes 100 iterations of this test while setting all breakpoints from
 the ``examples/tests/doublefree_nasty.py.data/gdb_pre`` file (you can specify

docs/source/Mux.rst

@@ -316,7 +316,7 @@ Injecting files
 
 You can run any test with any YAML file by::
 
-    avocado run sleeptest.py --multiplex file.yaml
+    avocado run sleeptest.py --mux-yaml file.yaml
 
 This puts the content of ``file.yaml`` into ``/run``
 location, which as mentioned in previous section, is the default ``mux-path``
@@ -328,7 +328,7 @@ when you have two files and you don't want the content to be merged into
 a single place becomming effectively a single blob, you can do that by
 giving a name to your yaml file::
 
-    avocado run sleeptest.py --multiplex duration:duration.yaml
+    avocado run sleeptest.py --mux-yaml duration:duration.yaml
 
 The content of ``duration.yaml`` is injected into ``/run/duration``. Still when
 keys from other files don't clash, you can use ``params.get(key)`` and retrieve
@@ -340,7 +340,7 @@ multiple files by using the same or different name, or even a complex
 Last but not least, advanced users can inject the file into whatever location
 they prefer by::
 
-    avocado run sleeptest.py --multiplex /my/variants/duration:duration.yaml
+    avocado run sleeptest.py --mux-yaml /my/variants/duration:duration.yaml
 
 Simple ``params.get(key)`` won't look in this location, which might be the
 intention of the test writer. There are several ways to access the values:

docs/source/Replay.rst

@@ -40,7 +40,7 @@ The replay feature will retrieve the original job urls, the multiplex
 tree and the configuration. Let's see another example, now using
 multiplex file::
 
-     $ avocado run /bin/true /bin/false --multiplex mux-environment.yaml
+     $ avocado run /bin/true /bin/false --mux-yaml mux-environment.yaml
      JOB ID     : bd6aa3b852d4290637b5e771b371537541043d1d
      JOB LOG    : $HOME/avocado/job-results/job-2016-01-11T21.56-bd6aa3b/job.log
      TESTS      : 48

docs/source/WritingTests.rst

@@ -101,7 +101,7 @@ the following multiplex file for sleeptest::
             long:
                 sleep_length: 5
 
-When running this example by ``avocado run $test --multiplex $file.yaml``
+When running this example by ``avocado run $test --mux-yaml $file.yaml``
 three variants are executed and the content is injected into ``/run`` namespace
 (see :doc:`Mux` for details). Every variant contains variables
 "type" and "sleep_length". To obtain the current value, you need the name
@@ -154,7 +154,7 @@ Using a multiplex file
 You may use the Avocado runner with a multiplex file to provide params and matrix
 generation for sleeptest just like::
 
-    $ avocado run sleeptest.py --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml
+    $ avocado run sleeptest.py --mux-yaml examples/tests/sleeptest.py.data/sleeptest.yaml
     JOB ID     : d565e8dec576d6040f894841f32a836c751f968f
     JOB LOG    : $HOME/avocado/job-results/job-2014-08-12T15.44-d565e8de/job.log
     TESTS      : 3
@@ -165,7 +165,7 @@ generation for sleeptest just like::
     TESTS TIME : 6.50 s
     JOB HTML   : $HOME/avocado/job-results/job-2014-08-12T15.44-d565e8de/html/results.html
 
-The ``--multiplex`` accepts either only ``$FILE_LOCATION`` or ``$INJECT_TO:$FILE_LOCATION``.
+The ``--mux-yaml`` accepts either only ``$FILE_LOCATION`` or ``$INJECT_TO:$FILE_LOCATION``.
 As explained in :doc:`Mux` without any path the content gets
 injected into ``/run`` in order to be in the default relative path location.
 The ``$INJECT_TO`` can be either relative path, then it's injected into
@@ -181,12 +181,12 @@ developer to get the value from this location (using path or adding the path to
 Note that, as your multiplex file specifies all parameters for sleeptest, you
 can't leave the test ID empty::
 
-    $ scripts/avocado run --multiplex examples/tests/sleeptest/sleeptest.yaml
+    $ scripts/avocado run --mux-yaml examples/tests/sleeptest/sleeptest.yaml
     Empty test ID. A test path or alias must be provided
 
 You can also execute multiple tests with the same multiplex file::
 
-    $ avocado run sleeptest.py synctest.py --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml
+    $ avocado run sleeptest.py synctest.py --mux-yaml examples/tests/sleeptest.py.data/sleeptest.yaml
     JOB ID     : cd20fc8d1714da6d4791c19322374686da68c45c
     JOB LOG    : $HOME/avocado/job-results/job-2016-05-04T09.25-cd20fc8/job.log
     TESTS      : 8
@@ -775,7 +775,7 @@ impact your test grid. You can account for that possibility and set up a
 
 ::
 
-    $ avocado run sleeptest.py --multiplex /tmp/sleeptest-example.yaml
+    $ avocado run sleeptest.py --mux-yaml /tmp/sleeptest-example.yaml
     JOB ID    : 6d5a2ff16bb92395100fbc3945b8d253308728c9
     JOB LOG   : $HOME/avocado/job-results/job-2014-08-12T15.52-6d5a2ff1/job.log
     TESTS     : 1
@@ -1099,7 +1099,7 @@ Here are the current variables that Avocado exports to the tests:
 +-------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TEST_SYSINFODIR | The system information directory      | $HOME/logs/job-results/job-2014-09-16T14.38-ac332e6/test-results/$HOME/my_test.sh.1/sysinfo         |
 +-------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
-| *                       | All variables from --multiplex-file   | TIMEOUT=60; IO_WORKERS=10; VM_BYTES=512M; ...                                                       |
+| *                       | All variables from --mux-yaml         | TIMEOUT=60; IO_WORKERS=10; VM_BYTES=512M; ...                                                       |
 +-------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 
 

selftests/functional/test_multiplex.py

@@ -65,13 +65,13 @@ class MultiplexTests(unittest.TestCase):
 
     def test_run_mplex_noid(self):
         cmd_line = ('./scripts/avocado run --job-results-dir %s --sysinfo=off '
-                    '--multiplex examples/tests/sleeptest.py.data/sleeptest.yaml' % self.tmpdir)
+                    '-m examples/tests/sleeptest.py.data/sleeptest.yaml' % self.tmpdir)
         expected_rc = exit_codes.AVOCADO_JOB_FAIL
         self.run_and_check(cmd_line, expected_rc)
 
     def test_run_mplex_passtest(self):
         cmd_line = ('./scripts/avocado run --job-results-dir %s --sysinfo=off '
-                    'passtest.py --multiplex '
+                    'passtest.py -m '
                     'examples/tests/sleeptest.py.data/sleeptest.yaml'
                     % self.tmpdir)
         expected_rc = exit_codes.AVOCADO_ALL_OK
@@ -79,14 +79,14 @@ class MultiplexTests(unittest.TestCase):
 
     def test_run_mplex_doublepass(self):
         cmd_line = ('./scripts/avocado run --job-results-dir %s --sysinfo=off '
-                    'passtest.py passtest.py --multiplex '
+                    'passtest.py passtest.py -m '
                     'examples/tests/sleeptest.py.data/sleeptest.yaml'
                     % self.tmpdir)
         self.run_and_check(cmd_line, expected_rc=0)
 
     def test_run_mplex_failtest(self):
         cmd_line = ('./scripts/avocado run --job-results-dir %s --sysinfo=off '
-                    'passtest.py failtest.py --multiplex '
+                    'passtest.py failtest.py -m '
                     'examples/tests/sleeptest.py.data/sleeptest.yaml'
                     % self.tmpdir)
         expected_rc = exit_codes.AVOCADO_TESTS_FAIL
@@ -94,7 +94,7 @@ class MultiplexTests(unittest.TestCase):
 
     def test_run_double_mplex(self):
         cmd_line = ('./scripts/avocado run --job-results-dir %s --sysinfo=off '
-                    'passtest.py --multiplex '
+                    'passtest.py -m '
                     'examples/tests/sleeptest.py.data/sleeptest.yaml '
                     'examples/tests/sleeptest.py.data/sleeptest.yaml'
                     % self.tmpdir)
@@ -107,7 +107,7 @@ class MultiplexTests(unittest.TestCase):
                             ('/run/long', 'This is very long\nmultiline\ntext.')):
             variant, msg = variant_msg
             cmd_line = ('./scripts/avocado run --job-results-dir %s --sysinfo=off examples/tests/env_variables.sh '
-                        '--multiplex examples/tests/env_variables.sh.data/env_variables.yaml '
+                        '-m examples/tests/env_variables.sh.data/env_variables.yaml '
                         '--filter-only %s --show-job-log' % (self.tmpdir, variant))
             expected_rc = exit_codes.AVOCADO_ALL_OK
             result = self.run_and_check(cmd_line, expected_rc)

selftests/functional/test_replay_basic.py

@@ -24,8 +24,7 @@ class ReplayTests(unittest.TestCase):
     def setUp(self):
         self.tmpdir = tempfile.mkdtemp(prefix='avocado_' + __name__)
         cmd_line = ('./scripts/avocado run passtest.py '
-                    '--multiplex '
-                    'examples/tests/sleeptest.py.data/sleeptest.yaml '
+                    '-m examples/tests/sleeptest.py.data/sleeptest.yaml '
                     '--job-results-dir %s --sysinfo=off --json -' %
                     self.tmpdir)
         expected_rc = exit_codes.AVOCADO_ALL_OK

selftests/functional/test_replay_external_runner.py

@@ -26,8 +26,7 @@ class ReplayExtRunnerTests(unittest.TestCase):
         self.tmpdir = tempfile.mkdtemp(prefix='avocado_' + __name__)
         test = script.make_script(os.path.join(self.tmpdir, 'test'), 'exit 0')
         cmd_line = ('./scripts/avocado run %s '
-                    '--multiplex '
-                    'examples/tests/sleeptest.py.data/sleeptest.yaml '
+                    '-m examples/tests/sleeptest.py.data/sleeptest.yaml '
                     '--external-runner /bin/bash '
                     '--job-results-dir %s --sysinfo=off --json -' %
                     (test, self.tmpdir))

selftests/unit/test_remote.py

@@ -105,7 +105,7 @@ _=/usr/bin/env''', exit_status=0)
 
         args = ("cd ~/avocado/tests; avocado run --force-job-id 1-sleeptest;0 "
                 "--json - --archive /tests/sleeptest /tests/other/test "
-                "passtest --multiplex ~/avocado/tests/foo.yaml "
+                "passtest -m ~/avocado/tests/foo.yaml "
                 "~/avocado/tests/bar/baz.yaml --dry-run")
         (Remote.should_receive('run')
          .with_args(args, timeout=61, ignore_status=True)