diff --git a/docs/source/WrapProcess.rst b/docs/source/WrapProcess.rst index 4b59463708..cf0aa26f00 100644 --- a/docs/source/WrapProcess.rst +++ b/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` diff --git a/man/avocado.rst b/man/avocado.rst index cf967cad3f..de5208b2f4 100644 --- a/man/avocado.rst +++ b/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 ===============================