Merge remote-tracking branch 'ruda/bug_documentation_wrappers2'

docs/source/WrapProcess.rst

@@ -10,14 +10,15 @@ interfere with the test behavior. That is, the wrapper should avoid
 changing the return status, standard output and standard error messages
 of the original process.
 
-The user can be specific about which program to wrap, or if that is omitted,
-a global wrapper that will apply to all programs called by the test.
+The user can be specific about which program to wrap (with a shell-like glob),
+or if that is omitted, a global wrapper that will apply to all
+programs called by the test.
 
 Usage
 -----
 
 This feature is implemented as a plugin, that adds the `--wrapper` option
-to the Avocado `run` command.  For a detailed explanation please consult the     
+to the Avocado `run` command.  For a detailed explanation, please consult the
 Avocado man page.
 
 Example of a transparent way of running strace as a wrapper::
@@ -31,7 +32,7 @@ To have all programs started by ``test.py`` wrapped with ``~/bin/my-wrapper.sh``
 
 To have only ``my-binary`` wrapped with ``~/bin/my-wrapper.sh``::
 
-  $ scripts/avocado run --wrapper ~/bin/my-wrapper.sh:my-binary tests/test.py
+    $ scripts/avocado run --wrapper ~/bin/my-wrapper.sh:*my-binary tests/test.py
 
 Caveats
 -------
@@ -47,13 +48,3 @@ Caveats
 * Only processes that are run with the :mod:`avocado.utils.process` APIs
   (and other API modules that make use of it, like mod:`avocado.utils.build`)
   are affected by this feature.
-
-* If paths are not absolute, then the process name matches with the base name,
-  so `--wrapper foo.sh:make` will match `/usr/bin/make`, `/opt/bin/make`
-  and `/long/path/to/make`.
-
-* When you use a relative path to a script, it will use the current path
-  of the running Avocado program. Example: If I'm running Avocado on
-  `/home/user/project/avocado`, then `avocado run --wrapper
-  examples/wrappers/strace.sh datadir`  will set the wrapper to
-  `/home/user/project/avocado/examples/wrappers/strace.sh`

man/avocado.rst

@@ -425,41 +425,38 @@ WRAP PROCESS IN TESTS
 =====================
 
 Avocado allows the instrumentation of applications being
-run by a test in a transparent way.
+run by a test in a transparent way. The user specifies a script
+("the wrapper") to be used to run the actual program called by the test.
 
-The user specify a script ("the wrapper") to be used to run the actual
-program called by the test.  If the instrument is
-implemented correctly, it should not interfere with the test behavior.
+If the instrument is implemented correctly, it should not interfere
+with the test behavior. So that, a perfect wrapper shall not
+change the return status, standard output and standard error messages
+of the process being executed.
 
-So it means that the wrapper should avoid to change the return status,
-standard output and standard error messages of the process.
+By using an optional parameter to the wrapper, you can specify a pattern
+in format of shell glob to select the "target binary" to wrap.
 
-By using an optional parameter to the wrapper, you can specify the
-"target binary" to wrap, so that for every program spawned by the test,
-the program name will be compared to the target binary.
-
-If the target binary is absolute path and the program name is absolute,
-then both paths should be equal to the wrapper take effect, otherwise
-the wrapper will not be used.
-
-For the case that the target binary is not absolute or the program name
-is not absolute, then both will be compared by its base name, ignoring paths.
+In this case, for every program spawned by the test,
+the program name will be compared to the pattern to decide
+whether to wrap it or not. You can have multiples wrappers and patterns
+defined.
 
 Examples::
 
  $ avocado run datadir --wrapper examples/wrappers/strace.sh
- $ avocado run datadir --wrapper examples/wrappers/ltrace.sh:make \
-                       --wrapper examples/wrappers/perf.sh:datadir
 
-Note that it's not possible to use ``--gdb-run-bin`` together
-with ``--wrapper``, they are incompatible.::
+Any command created by the test datadir will be wrapped on ``strace.sh``. ::
+
+ $ avocado run datadir --wrapper examples/wrappers/ltrace.sh:*make \
+                       --wrapper examples/wrappers/perf.sh:*datadir
+
+Any command that matches the pattern `*make` will
+be wrapper on ``ltrace.sh`` and the pattern ``*datadir`` will trigger
+the execution of ``perf.sh``. ::
 
- $ avocado run mytest --wrapper examples/wrappers/strace:/opt/bin/foo
+Note that it is not possible to use ``--gdb-run-bin`` together
+with ``--wrapper``, they are incompatible.
 
-In this case, the possible program that can wrapped by ``mytest`` is
-``/opt/bin/foo`` (absolute paths equal) and ``foo`` without absolute path
-will be wrapped too, but ``/opt/bin/foo`` will never be wrapped, because
-the absolute paths are not equal.
 
 RECORDING TEST REFERENCE OUTPUT
 ===============================