Merge "teststeps: Improvements and bugfixing of teststeps"

1 files changed, 81 insertions, 7 deletions

diff --git a/docs/testing/user/userguide/teststeps.rst b/docs/testing/user/userguide/teststeps.rst
index 5349d2ea..8be67310 100644
--- a/docs/testing/user/userguide/teststeps.rst
+++ b/docs/testing/user/userguide/teststeps.rst
@@ -29,6 +29,14 @@ does not pass validation the test will fail and terminate. The test will continu
 until a failure is detected or all steps pass. A csv report file is generated after
 a test completes with an OK or FAIL result.
 
+**NOTE**: It is possible to suppress validation process of given step by prefixing
+it by ``!`` (exclamation mark).
+In following example test execution won't fail if all traffic is dropped:
+
+.. code-block:: python
+
+    ['!trafficgen', 'send_traffic', {}]
+
 In case of performance test, the validation of steps is not performed and
 standard output files with results from traffic generator and underlying OS
 details are generated by vsperf.
@@ -75,6 +83,7 @@ of supported objects and their most common functions follows:
         * ``disable_stp br_name`` - disables Spanning Tree Protocol for bridge ``br_name``
         * ``enable_rstp br_name`` - enables Rapid Spanning Tree Protocol for bridge ``br_name``
         * ``disable_rstp br_name`` - disables Rapid Spanning Tree Protocol for bridge ``br_name``
+        * ``restart`` - restarts switch, which is useful for failover testcases
 
         Examples:
 
@@ -101,15 +110,26 @@ of supported objects and their most common functions follows:
 
         * ``start`` - starts a VNF based on VSPERF configuration
         * ``stop`` - gracefully terminates given VNF
+        * ``execute command [delay]`` - executes command `cmd` inside VNF; Optional
+          delay defines number of seconds to wait before next step is executed. Method
+          returns command output as a string.
+        * ``execute_and_wait command [timeout] [prompt]`` - executes command `cmd` inside
+          VNF; Optional timeout defines number of seconds to wait until ``prompt`` is detected.
+          Optional ``prompt`` defines a string, which is used as detection of successful command
+          execution. In case that prompt is not defined, then content of ``GUEST_PROMPT_LOGIN``
+          parameter will be used. Method returns command output as a string.
 
         Examples:
 
         .. code-block:: python
 
-            ['vnf1', 'start']
-            ['vnf2', 'start']
-            ['vnf2', 'stop']
-            ['vnf1', 'stop']
+            ['vnf1', 'start'],
+            ['vnf2', 'start'],
+            ['vnf1', 'execute_and_wait', 'ifconfig eth0 5.5.5.1/24 up'],
+            ['vnf2', 'execute_and_wait', 'ifconfig eth0 5.5.5.2/24 up', 120, 'root.*#'],
+            ['vnf2', 'execute_and_wait', 'ping -c1 5.5.5.1'],
+            ['vnf2', 'stop'],
+            ['vnf1', 'stop'],
 
     * ``trafficgen`` - triggers traffic generation
 
@@ -119,6 +139,8 @@ of supported objects and their most common functions follows:
           and given ``traffic`` dictionary. More details about ``traffic`` dictionary
           and its possible values are available at :ref:`Traffic Generator Integration Guide
           <step-5-supported-traffic-types>`
+        * ``get_results`` - returns dictionary with results collected from previous execution
+          of ``send_traffic``
 
         Examples:
 
@@ -126,7 +148,12 @@ of supported objects and their most common functions follows:
 
             ['trafficgen', 'send_traffic', {'traffic_type' : 'rfc2544_throughput'}]
 
-            ['trafficgen', 'send_traffic', {'traffic_type' : 'rfc2544_back2back', 'bidir' : 'True'}]
+            ['trafficgen', 'send_traffic', {'traffic_type' : 'rfc2544_back2back', 'bidir' : 'True'}],
+            ['trafficgen', 'get_results'],
+            ['tools', 'assert', '#STEP[-1][0]["frame_loss_percent"] < 0.05'],
+
+
+.. _step-driven-tests-variable-usage:
 
     * ``settings`` - reads or modifies VSPERF configuration
 
@@ -229,8 +256,7 @@ of supported objects and their most common functions follows:
           in case that condition is not ``True``
         * ``Eval expression`` - evaluates given expression as a python code and returns
           its result
-        * ``Exec_Shell command [regex]`` - executes a shell command and filters its output by
-          (optional) regular expression
+        * ``Exec_Shell command`` - executes a shell command
         * ``Exec_Python code`` - executes a python code
 
 
@@ -260,6 +286,23 @@ of supported objects and their most common functions follows:
 
         ['sleep', '60']
 
+    * ``log level message`` - is used to log ``message`` of given ``level`` into vsperf output.
+      Level is one of info, debug, warning or error.
+
+      Examples:
+
+      .. code-block:: python
+
+        ['log', 'error', 'tools $TOOLS']
+
+    * ``pdb`` - executes python debugger
+
+      Examples:
+
+      .. code-block:: python
+
+        ['pdb']
+
 Test Macros
 -----------
 
@@ -296,6 +339,15 @@ functionality:
 
                 ['vswitch', 'del_port', 'int_br0', '#STEP[-1][0]'],  # STEP 2
 
+Another option to refer to previous values, is to define an alias for given step
+by its first argument with '#' prefix. Alias must be unique and it can't be a number.
+Example of step alias usage:
+
+.. code-block:: python
+
+                ['#port1', 'vswitch', 'add_vport', 'int_br0'],
+                ['vswitch', 'del_port', 'int_br0', '#STEP[port1][0]'],
+
 Also commonly used steps can be created as a separate profile.
 
 .. code-block:: python
@@ -324,6 +376,28 @@ This profile can then be used inside other testcases
                      STEP_VSWITCH_PVP_FINIT
     }
 
+It is possible to refer to vsperf configuration parameters within step macros. Please
+see :ref:`step-driven-tests-variable-usage` for more details.
+
+In case that step returns a string or list of strings, then it is possible to
+filter such output by regular expression. This optional filter can be specified
+as a last step parameter with prefix '|'. Output will be split into separate lines
+and only matching records will be returned. It is also possible to return a specified
+group of characters from the matching lines, e.g. by regex ``|ID (\d+)``.
+
+Examples:
+
+.. code-block:: python
+
+   ['tools', 'exec_shell', "sudo $TOOLS['ovs-appctl'] dpif-netdev/pmd-rxq-show",
+    '|dpdkvhostuser0\s+queue-id: \d'],
+   ['tools', 'assert', 'len(#STEP[-1])==1'],
+
+   ['vnf', 'execute_and_wait', 'ethtool -L eth0 combined 2'],
+   ['vnf', 'execute_and_wait', 'ethtool -l eth0', '|Combined:\s+2'],
+   ['tools', 'assert', 'len(#STEP[-1])==2']
+
+
 HelloWorld and other basic Testcases
 ------------------------------------