Merge pull request #233 from ruda/manpage_multiplex_filters

Manpage: Update information regarding global filters and multiplexer.

avocado/plugins/multiplexer.py

@@ -49,7 +49,7 @@ class Multiplexer(plugin.Plugin):
                                  help='Shows the multiplex tree structure')
 
         self.parser.add_argument('-c', '--contents', action='store_true', default=False,
-                                 help='Keep temporary files generated by tests')
+                                 help="Shows the variant's content (variables)")
         super(Multiplexer, self).configure(self.parser)
 
     def run(self, args):

man/avocado.rst

@@ -6,7 +6,7 @@
 SYNOPSIS
 ========
 
- avocado [-h] [-v] [-V] [--logdir LOGDIR] [--loglevel LOG_LEVEL] [--plugins PLUGINS_DIR]
+ avocado [-h] [-v] [--logdir LOGDIR] [--loglevel LOG_LEVEL] [--plugins PLUGINS_DIR]
  {run,list,sysinfo,multiplex,plugins,datadir} ...
 
 DESCRIPTION
@@ -39,19 +39,25 @@ of avocado subcommands::
  plugins     List all plugins loaded
  datadir     List all relevant directories used by avocado
 
-To get usage instructions for a given subcommand run it with `--help`. Example::
+To get usage instructions for a given subcommand, run it with `--help`. Example::
 
  $ avocado multiplex --help
-
- usage: avocado multiplex [-h] [-t] [-c] [multiplex_file]
+ usage: avocado multiplex [-h] [--filter-only [FILTER_ONLY [FILTER_ONLY ...]]]
+                          [--filter-out [FILTER_OUT [FILTER_OUT ...]]] [-t]
+                          [-c]
+                          [multiplex_file]
 
  positional arguments:
-   multiplex_file  Path to a multiplex file
+   multiplex_file        Path to a multiplex file
 
  optional arguments:
-   -h, --help      show this help message and exit
-   -t, --tree      Shows the multiplex tree structure
-   -c, --contents  Keep temporary files generated by tests
+   -h, --help            show this help message and exit
+   --filter-only [FILTER_ONLY [FILTER_ONLY ...]]
+                         Filter only path(s) from multiplexing
+   --filter-out [FILTER_OUT [FILTER_OUT ...]]
+                         Filter out path(s) from multiplexing
+   -t, --tree            Shows the multiplex tree structure
+   -c, --contents        Shows the variant's content (variables)
 
 
 RUNNING A TEST
@@ -191,23 +197,54 @@ A command by the same name, `multiplex`, is available on the `avocado`
 command line tool, and enables you to see all the test scenarios that can
 be run::
 
- $ avocado multiplex tests/sleeptest.py.data/sleeptest.yaml
+ $ avocado multiplex examples/tests/sleeptest.py.data/sleeptest.yaml
  Variants generated:
- Variant 1:    ["short={'sleep_length': 0.5}"]
- Variant 2:    ["medium={'sleep_length': 1}"]
- Variant 3:    ["long={'sleep_length': 5}"]
- Variant 4:    ["longest={'sleep_length': 10}"]
+ Variant 1:    /short
+     sleep_length: 0.5
+ Variant 2:    /medium
+     sleep_length: 1
+ Variant 3:    /long
+     sleep_length: 5
+ Variant 4:    /longest
+     sleep_length: 10
 
- $ avocado run --multiplex tests/sleeptest.py.data/sleeptest.yaml sleeptest
+ $ avocado run --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml sleeptest
 
 And the output should look like::
 
- ...
- (1/4) sleeptest.py: PASS (0.50 s)
- (2/4) sleeptest.py.1: PASS (1.00 s)
- (3/4) sleeptest.py.2: PASS (5.01 s)
- (4/4) sleeptest.py.3: PASS (10.01 s)
- ...
+ JOB ID    : <id>
+ JOB LOG   : /home/<user>/avocado/job-results/job-<date-<shortid>/job.log
+ TESTS     : 4
+ (1/4) sleeptest.py.1:  PASS (0.50 s)
+ (2/4) sleeptest.py.2:  PASS (1.00 s)
+ (3/4) sleeptest.py.3:  PASS (5.01 s)
+ (4/4) sleeptest.py.4:  PASS (10.01 s)
+ PASS      : 4
+ ERROR     : 0
+ FAIL      : 0
+ SKIP      : 0
+ WARN      : 0
+ NOT FOUND : 0
+ TIME      : 16.53 s
+
+The `multiplex` plugin and the test runner supports two kinds of global
+filters, through the command line options `--filter-only` and `--filter-out`.
+The `filter-only` exclusively includes one or more paths and
+the `filter-out` removes one or more paths from being processed.
+
+From the previous example, if we are interested to use the variants `/medium`
+and `longest`, we do the following command line::
+
+ $ avocado run --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml sleeptest \
+       --filter-only /medium /longest
+
+And if you want to remove `/small` from the variants created,
+we do the following::
+
+ $ avocado run --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml sleeptest \
+       --filter-out /medium
+
+Note that both filters can be arranged in the same command line.
 
 DEBUGGING BINARIES RUN AS PART OF A TEST
 ========================================