docs/testing/user/userguide/teststeps.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation, AT&T and others.
   4
   5 .. _step-driven-tests:
   6
   7 Step driven tests
   8 =================
   9
  10 In general, test scenarios are defined by a ``deployment`` used in the particular
  11 test case definition. The chosen deployment scenario will take care of the vSwitch
  12 configuration, deployment of VNFs and it can also affect configuration of a traffic
  13 generator. In order to allow a more flexible way of testcase scripting, VSPERF supports
  14 a detailed step driven testcase definition. It can be used to configure and
  15 program vSwitch, deploy and terminate VNFs, execute a traffic generator,
  16 modify a VSPERF configuration, execute external commands, etc.
  17
  18 Execution of step driven tests is done on a step by step work flow starting
  19 with step 0 as defined inside the test case. Each step of the test increments
  20 the step number by one which is indicated in the log.
  21
  22 .. code-block:: console
  23
  24     (testcases.integration) - Step 0 'vswitch add_vport ['br0']' start
  25
  26 Test steps are defined as a list of steps within a ``TestSteps`` item of test
  27 case definition. Each step is a list with following structure:
  28
  29 .. code-block:: python
  30
  31     '[' [ optional-alias ',' ] test-object ',' test-function [ ',' optional-function-params ] '],'
  32
  33 Step driven tests can be used for both performance and integration testing.
  34 In case of integration test, each step in the test case is validated. If a step
  35 does not pass validation the test will fail and terminate. The test will continue
  36 until a failure is detected or all steps pass. A csv report file is generated after
  37 a test completes with an OK or FAIL result.
  38
  39 **NOTE**: It is possible to suppress validation process of given step by prefixing
  40 it by ``!`` (exclamation mark).
  41 In following example test execution won't fail if all traffic is dropped:
  42
  43 .. code-block:: python
  44
  45     ['!trafficgen', 'send_traffic', {}]
  46
  47 In case of performance test, the validation of steps is not performed and
  48 standard output files with results from traffic generator and underlying OS
  49 details are generated by vsperf.
  50
  51 Step driven testcases can be used in two different ways:
  52
  53     # description of full testcase - in this case ``clean`` deployment is used
  54       to indicate that vsperf should neither configure vSwitch nor deploy any VNF.
  55       Test shall perform all required vSwitch configuration and programming and
  56       deploy required number of VNFs.
  57
  58     # modification of existing deployment - in this case, any of supported
  59       deployments can be used to perform initial vSwitch configuration and
  60       deployment of VNFs. Additional actions defined by TestSteps can be used
  61       to alter vSwitch configuration or deploy additional VNFs. After the last
  62       step is processed, the test execution will continue with traffic execution.
  63
  64 Test objects and their functions
  65 --------------------------------
  66
  67 Every test step can call a function of one of the supported test objects. In general
  68 any existing function of supported test object can be called by test step. In case
  69 that step validation is required (valid for integration test steps, which are not
  70 suppressed), then appropriate ``validate_`` method must be implemented.
  71
  72 The list of supported objects and their most common functions is listed below. Please
  73 check implementation of test objects for full list of implemented functions and their
  74 parameters.
  75
  76     * ``vswitch`` - provides functions for vSwitch configuration
  77
  78       List of supported functions:
  79
  80         * ``add_switch br_name`` - creates a new switch (bridge) with given ``br_name``
  81         * ``del_switch br_name`` - deletes switch (bridge) with given ``br_name``
  82         * ``add_phy_port br_name`` - adds a physical port into bridge specified by ``br_name``
  83         * ``add_vport br_name`` - adds a virtual port into bridge specified by ``br_name``
  84         * ``del_port br_name port_name`` - removes physical or virtual port specified by
  85           ``port_name`` from bridge ``br_name``
  86         * ``add_flow br_name flow`` - adds flow specified by ``flow`` dictionary into
  87           the bridge ``br_name``; Content of flow dictionary will be passed to the vSwitch.
  88           In case of Open vSwitch it will be passed to the ``ovs-ofctl add-flow`` command.
  89           Please see Open vSwitch documentation for the list of supported flow parameters.
  90         * ``del_flow br_name [flow]`` - deletes flow specified by ``flow`` dictionary from
  91           bridge ``br_name``; In case that optional parameter ``flow`` is not specified
  92           or set to an empty dictionary ``{}``, then all flows from bridge ``br_name``
  93           will be deleted.
  94         * ``dump_flows br_name`` - dumps all flows from bridge specified by ``br_name``
  95         * ``enable_stp br_name`` - enables Spanning Tree Protocol for bridge ``br_name``
  96         * ``disable_stp br_name`` - disables Spanning Tree Protocol for bridge ``br_name``
  97         * ``enable_rstp br_name`` - enables Rapid Spanning Tree Protocol for bridge ``br_name``
  98         * ``disable_rstp br_name`` - disables Rapid Spanning Tree Protocol for bridge ``br_name``
  99         * ``restart`` - restarts switch, which is useful for failover testcases
 100
 101         Examples:
 102
 103         .. code-block:: python
 104
 105             ['vswitch', 'add_switch', 'int_br0']
 106
 107             ['vswitch', 'del_switch', 'int_br0']
 108
 109             ['vswitch', 'add_phy_port', 'int_br0']
 110
 111             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]']
 112
 113             ['vswitch', 'add_flow', 'int_br0', {'in_port': '1', 'actions': ['output:2'],
 114              'idle_timeout': '0'}],
 115
 116             ['vswitch', 'enable_rstp', 'int_br0']
 117
 118     * ``vnf[ID]`` - provides functions for deployment and termination of VNFs; Optional
 119       alfanumerical ``ID`` is used for VNF identification in case that testcase
 120       deploys multiple VNFs.
 121
 122       List of supported functions:
 123
 124         * ``start`` - starts a VNF based on VSPERF configuration
 125         * ``stop`` - gracefully terminates given VNF
 126         * ``execute command [delay]`` - executes command `cmd` inside VNF; Optional
 127           delay defines number of seconds to wait before next step is executed. Method
 128           returns command output as a string.
 129         * ``execute_and_wait command [timeout] [prompt]`` - executes command `cmd` inside
 130           VNF; Optional timeout defines number of seconds to wait until ``prompt`` is detected.
 131           Optional ``prompt`` defines a string, which is used as detection of successful command
 132           execution. In case that prompt is not defined, then content of ``GUEST_PROMPT_LOGIN``
 133           parameter will be used. Method returns command output as a string.
 134
 135         Examples:
 136
 137         .. code-block:: python
 138
 139             ['vnf1', 'start'],
 140             ['vnf2', 'start'],
 141             ['vnf1', 'execute_and_wait', 'ifconfig eth0 5.5.5.1/24 up'],
 142             ['vnf2', 'execute_and_wait', 'ifconfig eth0 5.5.5.2/24 up', 120, 'root.*#'],
 143             ['vnf2', 'execute_and_wait', 'ping -c1 5.5.5.1'],
 144             ['vnf2', 'stop'],
 145             ['vnf1', 'stop'],
 146
 147     * ``VNF[ID]`` - provides access to VNFs deployed automatically by testcase deployment
 148       scenario. For Example ``pvvp`` deployment automatically starts two VNFs before any
 149       TestStep is executed. It is possible to access these VNFs by VNF0 and VNF1 labels.
 150
 151       List of supported functions is identical to ``vnf[ID]`` option above except functions
 152       ``start`` and ``stop``.
 153
 154       Examples:
 155
 156       .. code-block:: python
 157
 158           ['VNF0', 'execute_and_wait', 'ifconfig eth2 5.5.5.1/24 up'],
 159           ['VNF1', 'execute_and_wait', 'ifconfig eth2 5.5.5.2/24 up', 120, 'root.*#'],
 160           ['VNF2', 'execute_and_wait', 'ping -c1 5.5.5.1'],
 161
 162     * ``trafficgen`` - triggers traffic generation
 163
 164       List of supported functions:
 165
 166         * ``send_traffic traffic`` - starts a traffic based on the vsperf configuration
 167           and given ``traffic`` dictionary. More details about ``traffic`` dictionary
 168           and its possible values are available at :ref:`Traffic Generator Integration Guide
 169           <step-5-supported-traffic-types>`
 170         * ``get_results`` - returns dictionary with results collected from previous execution
 171           of ``send_traffic``
 172
 173         Examples:
 174
 175         .. code-block:: python
 176
 177             ['trafficgen', 'send_traffic', {'traffic_type' : 'rfc2544_throughput'}]
 178
 179             ['trafficgen', 'send_traffic', {'traffic_type' : 'rfc2544_back2back', 'bidir' : 'True'}],
 180             ['trafficgen', 'get_results'],
 181             ['tools', 'assert', '#STEP[-1][0]["frame_loss_percent"] < 0.05'],
 182
 183
 184 .. _step-driven-tests-variable-usage:
 185
 186     * ``settings`` - reads or modifies VSPERF configuration
 187
 188       List of supported functions:
 189
 190         * ``getValue param`` - returns value of given ``param``
 191         * ``setValue param value`` - sets value of ``param`` to given ``value``
 192         * ``resetValue param`` - if ``param`` was overridden by ``TEST_PARAMS`` (e.g. by "Parameters"
 193           section of the test case definition), then it will be set to its original value.
 194
 195         Examples:
 196
 197         .. code-block:: python
 198
 199             ['settings', 'getValue', 'TOOLS']
 200
 201             ['settings', 'setValue', 'GUEST_USERNAME', ['root']]
 202
 203             ['settings', 'resetValue', 'WHITELIST_NICS'],
 204
 205         It is possible and more convenient to access any VSPERF configuration option directly
 206         via ``$NAME`` notation. Option evaluation is done during runtime and vsperf will
 207         automatically translate it to the appropriate call of ``settings.getValue``.
 208         If the referred parameter does not exist, then vsperf will keep ``$NAME``
 209         string untouched and it will continue with testcase execution. The reason is to
 210         avoid test execution failure in case that ``$`` sign has been used from different
 211         reason than vsperf parameter evaluation.
 212
 213         **NOTE:** It is recommended to use ``${NAME}`` notation for any shell parameters
 214         used within ``Exec_Shell`` call to avoid a clash with configuration parameter
 215         evaluation.
 216
 217         **NOTE:** It is possible to refer to vsperf parameter value by ``#PARAM()`` macro
 218         (see :ref:`overriding-parameters-documentation`. However ``#PARAM()`` macro is
 219         evaluated at the beginning of vsperf execution and it will not reflect any changes
 220         made to the vsperf configuration during runtime. On the other hand ``$NAME``
 221         notation is evaluated during test execution and thus it contains any modifications
 222         to the configuration parameter made by vsperf (e.g. ``TOOLS`` and ``NICS``
 223         dictionaries) or by testcase definition (e.g. ``TRAFFIC`` dictionary).
 224
 225         Examples:
 226
 227         .. code-block:: python
 228
 229             ['tools', 'exec_shell', "$TOOLS['ovs-vsctl'] show"]
 230
 231             ['settings', 'setValue', 'TRAFFICGEN_IXIA_PORT2', '$TRAFFICGEN_IXIA_PORT1'],
 232
 233             ['vswitch', 'add_flow', 'int_br0',
 234              {'in_port': '#STEP[1][1]',
 235               'dl_type': '0x800',
 236               'nw_proto': '17',
 237               'nw_dst': '$TRAFFIC["l3"]["dstip"]/8',
 238               'actions': ['output:#STEP[2][1]']
 239              }
 240             ]
 241
 242     * ``namespace`` - creates or modifies network namespaces
 243
 244       List of supported functions:
 245
 246         * ``create_namespace name`` - creates new namespace with given ``name``
 247         * ``delete_namespace name`` - deletes namespace specified by its ``name``
 248         * ``assign_port_to_namespace port name [port_up]`` - assigns NIC specified by ``port``
 249           into given namespace ``name``; If optional parameter ``port_up`` is set to ``True``,
 250           then port will be brought up.
 251         * ``add_ip_to_namespace_eth port name addr cidr`` - assigns an IP address ``addr``/``cidr``
 252           to the NIC specified by ``port`` within namespace ``name``
 253         * ``reset_port_to_root port name`` - returns given ``port`` from namespace ``name`` back
 254           to the root namespace
 255
 256         Examples:
 257
 258         .. code-block:: python
 259
 260             ['namespace', 'create_namespace', 'testns']
 261
 262             ['namespace', 'assign_port_to_namespace', 'eth0', 'testns']
 263
 264     * ``veth`` - manipulates with eth and veth devices
 265
 266       List of supported functions:
 267
 268         * ``add_veth_port port peer_port`` - adds a pair of veth ports named ``port`` and
 269           ``peer_port``
 270         * ``del_veth_port port peer_port`` - deletes a veth port pair specified by ``port``
 271           and ``peer_port``
 272         * ``bring_up_eth_port eth_port [namespace]`` - brings up ``eth_port`` in (optional)
 273           ``namespace``
 274
 275         Examples:
 276
 277         .. code-block:: python
 278
 279             ['veth', 'add_veth_port', 'veth', 'veth1']
 280
 281             ['veth', 'bring_up_eth_port', 'eth1']
 282
 283     * ``tools`` - provides a set of helper functions
 284
 285       List of supported functions:
 286
 287         * ``Assert condition`` - evaluates given ``condition`` and raises ``AssertionError``
 288           in case that condition is not ``True``
 289         * ``Eval expression`` - evaluates given expression as a python code and returns
 290           its result
 291         * ``Exec_Shell command`` - executes a shell command and wait until it finishes
 292         * ``Exec_Shell_Background command`` - executes a shell command at background;
 293           Command will be automatically terminated at the end of testcase execution.
 294         * ``Exec_Python code`` - executes a python code
 295
 296
 297         Examples:
 298
 299         .. code-block:: python
 300
 301             ['tools', 'exec_shell', 'numactl -H', 'available: ([0-9]+)']
 302             ['tools', 'assert', '#STEP[-1][0]>1']
 303
 304     * ``wait`` - is used for test case interruption. This object doesn't have
 305       any functions. Once reached, vsperf will pause test execution and waits
 306       for press of ``Enter key``. It can be used during testcase design
 307       for debugging purposes.
 308
 309       Examples:
 310
 311       .. code-block:: python
 312
 313         ['wait']
 314
 315     * ``sleep`` - is used to pause testcase execution for defined number of seconds.
 316
 317       Examples:
 318
 319       .. code-block:: python
 320
 321         ['sleep', '60']
 322
 323     * ``log level message`` - is used to log ``message`` of given ``level`` into vsperf output.
 324       Level is one of info, debug, warning or error.
 325
 326       Examples:
 327
 328       .. code-block:: python
 329
 330         ['log', 'error', 'tools $TOOLS']
 331
 332     * ``pdb`` - executes python debugger
 333
 334       Examples:
 335
 336       .. code-block:: python
 337
 338         ['pdb']
 339
 340 Test Macros
 341 -----------
 342
 343 Test profiles can include macros as part of the test step. Each step in the
 344 profile may return a value such as a port name. Recall macros use #STEP to
 345 indicate the recalled value inside the return structure. If the method the
 346 test step calls returns a value it can be later recalled, for example:
 347
 348 .. code-block:: python
 349
 350     {
 351         "Name": "vswitch_add_del_vport",
 352         "Deployment": "clean",
 353         "Description": "vSwitch - add and delete virtual port",
 354         "TestSteps": [
 355                 ['vswitch', 'add_switch', 'int_br0'],               # STEP 0
 356                 ['vswitch', 'add_vport', 'int_br0'],                # STEP 1
 357                 ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],  # STEP 2
 358                 ['vswitch', 'del_switch', 'int_br0'],               # STEP 3
 359              ]
 360     }
 361
 362 This test profile uses the vswitch add_vport method which returns a string
 363 value of the port added. This is later called by the del_port method using the
 364 name from step 1.
 365
 366 It is also possible to use negative indexes in step macros. In that case
 367 ``#STEP[-1]`` will refer to the result from previous step, ``#STEP[-2]``
 368 will refer to result of step called before previous step, etc. It means,
 369 that you could change ``STEP 2`` from previous example to achieve the same
 370 functionality:
 371
 372 .. code-block:: python
 373
 374                 ['vswitch', 'del_port', 'int_br0', '#STEP[-1][0]'],  # STEP 2
 375
 376 Another option to refer to previous values, is to define an alias for given step
 377 by its first argument with '#' prefix. Alias must be unique and it can't be a number.
 378 Example of step alias usage:
 379
 380 .. code-block:: python
 381
 382                 ['#port1', 'vswitch', 'add_vport', 'int_br0'],
 383                 ['vswitch', 'del_port', 'int_br0', '#STEP[port1][0]'],
 384
 385 Also commonly used steps can be created as a separate profile.
 386
 387 .. code-block:: python
 388
 389     STEP_VSWITCH_PVP_INIT = [
 390         ['vswitch', 'add_switch', 'int_br0'],           # STEP 0
 391         ['vswitch', 'add_phy_port', 'int_br0'],         # STEP 1
 392         ['vswitch', 'add_phy_port', 'int_br0'],         # STEP 2
 393         ['vswitch', 'add_vport', 'int_br0'],            # STEP 3
 394         ['vswitch', 'add_vport', 'int_br0'],            # STEP 4
 395     ]
 396
 397 This profile can then be used inside other testcases
 398
 399 .. code-block:: python
 400
 401     {
 402         "Name": "vswitch_pvp",
 403         "Deployment": "clean",
 404         "Description": "vSwitch - configure switch and one vnf",
 405         "TestSteps": STEP_VSWITCH_PVP_INIT +
 406                      [
 407                         ['vnf', 'start'],
 408                         ['vnf', 'stop'],
 409                      ] +
 410                      STEP_VSWITCH_PVP_FINIT
 411     }
 412
 413 It is possible to refer to vsperf configuration parameters within step macros. Please
 414 see :ref:`step-driven-tests-variable-usage` for more details.
 415
 416 In case that step returns a string or list of strings, then it is possible to
 417 filter such output by regular expression. This optional filter can be specified
 418 as a last step parameter with prefix '|'. Output will be split into separate lines
 419 and only matching records will be returned. It is also possible to return a specified
 420 group of characters from the matching lines, e.g. by regex ``|ID (\d+)``.
 421
 422 Examples:
 423
 424 .. code-block:: python
 425
 426    ['tools', 'exec_shell', "sudo $TOOLS['ovs-appctl'] dpif-netdev/pmd-rxq-show",
 427     '|dpdkvhostuser0\s+queue-id: \d'],
 428    ['tools', 'assert', 'len(#STEP[-1])==1'],
 429
 430    ['vnf', 'execute_and_wait', 'ethtool -L eth0 combined 2'],
 431    ['vnf', 'execute_and_wait', 'ethtool -l eth0', '|Combined:\s+2'],
 432    ['tools', 'assert', 'len(#STEP[-1])==2']
 433
 434
 435 HelloWorld and other basic Testcases
 436 ------------------------------------
 437
 438 The following examples are for demonstration purposes.
 439 You can run them by copying and pasting into the
 440 conf/integration/01_testcases.conf file.
 441 A command-line instruction is shown at the end of each
 442 example.
 443
 444 HelloWorld
 445 ^^^^^^^^^^
 446
 447 The first example is a HelloWorld testcase.
 448 It simply creates a bridge with 2 physical ports, then sets up a flow to drop
 449 incoming packets from the port that was instantiated at the STEP #1.
 450 There's no interaction with the traffic generator.
 451 Then the flow, the 2 ports and the bridge are deleted.
 452 'add_phy_port' method creates a 'dpdk' type interface that will manage the
 453 physical port. The string value returned is the port name that will be referred
 454 by 'del_port' later on.
 455
 456 .. code-block:: python
 457
 458     {
 459         "Name": "HelloWorld",
 460         "Description": "My first testcase",
 461         "Deployment": "clean",
 462         "TestSteps": [
 463             ['vswitch', 'add_switch', 'int_br0'],   # STEP 0
 464             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1
 465             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2
 466             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 467                 'actions': ['drop'], 'idle_timeout': '0'}],
 468             ['vswitch', 'del_flow', 'int_br0'],
 469             ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],
 470             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'],
 471             ['vswitch', 'del_switch', 'int_br0'],
 472         ]
 473
 474     },
 475
 476 To run HelloWorld test:
 477
 478   .. code-block:: console
 479
 480     ./vsperf --conf-file user_settings.py --integration HelloWorld
 481
 482 Specify a Flow by the IP address
 483 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 484
 485 The next example shows how to explicitly set up a flow by specifying a
 486 destination IP address.
 487 All packets received from the port created at STEP #1 that have a destination
 488 IP address = 90.90.90.90 will be forwarded to the port created at the STEP #2.
 489
 490 .. code-block:: python
 491
 492     {
 493         "Name": "p2p_rule_l3da",
 494         "Description": "Phy2Phy with rule on L3 Dest Addr",
 495         "Deployment": "clean",
 496         "biDirectional": "False",
 497         "TestSteps": [
 498             ['vswitch', 'add_switch', 'int_br0'],   # STEP 0
 499             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1
 500             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2
 501             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 502                 'dl_type': '0x0800', 'nw_dst': '90.90.90.90', \
 503                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 504             ['trafficgen', 'send_traffic', \
 505                 {'traffic_type' : 'rfc2544_continuous'}],
 506             ['vswitch', 'dump_flows', 'int_br0'],   # STEP 5
 507             ['vswitch', 'del_flow', 'int_br0'],     # STEP 7 == del-flows
 508             ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],
 509             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'],
 510             ['vswitch', 'del_switch', 'int_br0'],
 511         ]
 512     },
 513
 514 To run the test:
 515
 516   .. code-block:: console
 517
 518     ./vsperf --conf-file user_settings.py --integration p2p_rule_l3da
 519
 520 Multistream feature
 521 ^^^^^^^^^^^^^^^^^^^
 522
 523 The next testcase uses the multistream feature.
 524 The traffic generator will send packets with different UDP ports.
 525 That is accomplished by using "Stream Type" and "MultiStream" keywords.
 526 4 different flows are set to forward all incoming packets.
 527
 528 .. code-block:: python
 529
 530     {
 531         "Name": "multistream_l4",
 532         "Description": "Multistream on UDP ports",
 533         "Deployment": "clean",
 534         "Parameters": {
 535             'TRAFFIC' : {
 536                 "multistream": 4,
 537                 "stream_type": "L4",
 538             },
 539         },
 540         "TestSteps": [
 541             ['vswitch', 'add_switch', 'int_br0'],   # STEP 0
 542             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1
 543             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2
 544             # Setup Flows
 545             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 546                 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '0', \
 547                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 548             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 549                 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '1', \
 550                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 551             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 552                 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '2', \
 553                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 554             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 555                 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '3', \
 556                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 557             # Send mono-dir traffic
 558             ['trafficgen', 'send_traffic', \
 559                 {'traffic_type' : 'rfc2544_continuous', \
 560                 'bidir' : 'False'}],
 561             # Clean up
 562             ['vswitch', 'del_flow', 'int_br0'],
 563             ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],
 564             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'],
 565             ['vswitch', 'del_switch', 'int_br0'],
 566          ]
 567     },
 568
 569 To run the test:
 570
 571   .. code-block:: console
 572
 573     ./vsperf --conf-file user_settings.py --integration multistream_l4
 574
 575 PVP with a VM Replacement
 576 ^^^^^^^^^^^^^^^^^^^^^^^^^
 577
 578 This example launches a 1st VM in a PVP topology, then the VM is replaced
 579 by another VM.
 580 When VNF setup parameter in ./conf/04_vnf.conf is "QemuDpdkVhostUser"
 581 'add_vport' method creates a 'dpdkvhostuser' type port to connect a VM.
 582
 583 .. code-block:: python
 584
 585     {
 586         "Name": "ex_replace_vm",
 587         "Description": "PVP with VM replacement",
 588         "Deployment": "clean",
 589         "TestSteps": [
 590             ['vswitch', 'add_switch', 'int_br0'],       # STEP 0
 591             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 1
 592             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 2
 593             ['vswitch', 'add_vport', 'int_br0'],        # STEP 3    vm1
 594             ['vswitch', 'add_vport', 'int_br0'],        # STEP 4
 595
 596             # Setup Flows
 597             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 598                 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}],
 599             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \
 600                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 601             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[2][1]', \
 602                 'actions': ['output:#STEP[4][1]'], 'idle_timeout': '0'}],
 603             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[3][1]', \
 604                 'actions': ['output:#STEP[1][1]'], 'idle_timeout': '0'}],
 605
 606             # Start VM 1
 607             ['vnf1', 'start'],
 608             # Now we want to replace VM 1 with another VM
 609             ['vnf1', 'stop'],
 610
 611             ['vswitch', 'add_vport', 'int_br0'],        # STEP 11    vm2
 612             ['vswitch', 'add_vport', 'int_br0'],        # STEP 12
 613             ['vswitch', 'del_flow', 'int_br0'],
 614             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 615                 'actions': ['output:#STEP[11][1]'], 'idle_timeout': '0'}],
 616             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[12][1]', \
 617                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 618
 619             # Start VM 2
 620             ['vnf2', 'start'],
 621             ['vnf2', 'stop'],
 622             ['vswitch', 'dump_flows', 'int_br0'],
 623
 624             # Clean up
 625             ['vswitch', 'del_flow', 'int_br0'],
 626             ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],
 627             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'],
 628             ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'],    # vm1
 629             ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'],
 630             ['vswitch', 'del_port', 'int_br0', '#STEP[11][0]'],   # vm2
 631             ['vswitch', 'del_port', 'int_br0', '#STEP[12][0]'],
 632             ['vswitch', 'del_switch', 'int_br0'],
 633         ]
 634     },
 635
 636 To run the test:
 637
 638   .. code-block:: console
 639
 640      ./vsperf --conf-file user_settings.py --integration ex_replace_vm
 641
 642 VM with a Linux bridge
 643 ^^^^^^^^^^^^^^^^^^^^^^
 644
 645 This example setups a PVP topology and routes traffic to the VM based on
 646 the destination IP address. A command-line parameter is used to select a Linux
 647 bridge as a guest loopback application. It is also possible to select a guest
 648 loopback application by a configuration option ``GUEST_LOOPBACK``.
 649
 650 .. code-block:: python
 651
 652     {
 653         "Name": "ex_pvp_rule_l3da",
 654         "Description": "PVP with flow on L3 Dest Addr",
 655         "Deployment": "clean",
 656         "TestSteps": [
 657             ['vswitch', 'add_switch', 'int_br0'],       # STEP 0
 658             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 1
 659             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 2
 660             ['vswitch', 'add_vport', 'int_br0'],        # STEP 3    vm1
 661             ['vswitch', 'add_vport', 'int_br0'],        # STEP 4
 662             # Setup Flows
 663             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 664                 'dl_type': '0x0800', 'nw_dst': '90.90.90.90', \
 665                 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}],
 666             # Each pkt from the VM is forwarded to the 2nd dpdk port
 667             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \
 668                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 669             # Start VMs
 670             ['vnf1', 'start'],
 671             ['trafficgen', 'send_traffic', \
 672                 {'traffic_type' : 'rfc2544_continuous', \
 673                 'bidir' : 'False'}],
 674             ['vnf1', 'stop'],
 675             # Clean up
 676             ['vswitch', 'dump_flows', 'int_br0'],       # STEP 10
 677             ['vswitch', 'del_flow', 'int_br0'],         # STEP 11
 678             ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],
 679             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'],
 680             ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'],  # vm1 ports
 681             ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'],
 682             ['vswitch', 'del_switch', 'int_br0'],
 683         ]
 684     },
 685
 686 To run the test:
 687
 688   .. code-block:: console
 689
 690     ./vsperf --conf-file user_settings.py --test-params \
 691             "GUEST_LOOPBACK=['linux_bridge']" --integration ex_pvp_rule_l3da
 692
 693 Forward packets based on UDP port
 694 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 695
 696 This examples launches 2 VMs connected in parallel.
 697 Incoming packets will be forwarded to one specific VM depending on the
 698 destination UDP port.
 699
 700 .. code-block:: python
 701
 702     {
 703         "Name": "ex_2pvp_rule_l4dp",
 704         "Description": "2 PVP with flows on L4 Dest Port",
 705         "Deployment": "clean",
 706         "Parameters": {
 707             'TRAFFIC' : {
 708                 "multistream": 2,
 709                 "stream_type": "L4",
 710             },
 711         },
 712         "TestSteps": [
 713             ['vswitch', 'add_switch', 'int_br0'],       # STEP 0
 714             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 1
 715             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 2
 716             ['vswitch', 'add_vport', 'int_br0'],        # STEP 3    vm1
 717             ['vswitch', 'add_vport', 'int_br0'],        # STEP 4
 718             ['vswitch', 'add_vport', 'int_br0'],        # STEP 5    vm2
 719             ['vswitch', 'add_vport', 'int_br0'],        # STEP 6
 720             # Setup Flows to reply ICMPv6 and similar packets, so to
 721             # avoid flooding internal port with their re-transmissions
 722             ['vswitch', 'add_flow', 'int_br0', \
 723                 {'priority': '1', 'dl_src': '00:00:00:00:00:01', \
 724                 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}],
 725             ['vswitch', 'add_flow', 'int_br0', \
 726                 {'priority': '1', 'dl_src': '00:00:00:00:00:02', \
 727                 'actions': ['output:#STEP[4][1]'], 'idle_timeout': '0'}],
 728             ['vswitch', 'add_flow', 'int_br0', \
 729                 {'priority': '1', 'dl_src': '00:00:00:00:00:03', \
 730                 'actions': ['output:#STEP[5][1]'], 'idle_timeout': '0'}],
 731             ['vswitch', 'add_flow', 'int_br0', \
 732                 {'priority': '1', 'dl_src': '00:00:00:00:00:04', \
 733                 'actions': ['output:#STEP[6][1]'], 'idle_timeout': '0'}],
 734             # Forward UDP packets depending on dest port
 735             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 736                 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '0', \
 737                 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}],
 738             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \
 739                 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '1', \
 740                 'actions': ['output:#STEP[5][1]'], 'idle_timeout': '0'}],
 741             # Send VM output to phy port #2
 742             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \
 743                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 744             ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[6][1]', \
 745                 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}],
 746             # Start VMs
 747             ['vnf1', 'start'],                          # STEP 16
 748             ['vnf2', 'start'],                          # STEP 17
 749             ['trafficgen', 'send_traffic', \
 750                 {'traffic_type' : 'rfc2544_continuous', \
 751                 'bidir' : 'False'}],
 752             ['vnf1', 'stop'],
 753             ['vnf2', 'stop'],
 754             ['vswitch', 'dump_flows', 'int_br0'],
 755             # Clean up
 756             ['vswitch', 'del_flow', 'int_br0'],
 757             ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'],
 758             ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'],
 759             ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'],  # vm1 ports
 760             ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'],
 761             ['vswitch', 'del_port', 'int_br0', '#STEP[5][0]'],  # vm2 ports
 762             ['vswitch', 'del_port', 'int_br0', '#STEP[6][0]'],
 763             ['vswitch', 'del_switch', 'int_br0'],
 764         ]
 765     },
 766
 767 The same test can be written in a shorter form using "Deployment" : "pvpv".
 768
 769 To run the test:
 770
 771   .. code-block:: console
 772
 773     ./vsperf --conf-file user_settings.py --integration ex_2pvp_rule_l4dp
 774
 775 Modification of existing PVVP deployment
 776 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 777
 778 This is an example of modification of a standard deployment scenario with additional TestSteps.
 779 Standard PVVP scenario is used to configure a vSwitch and to deploy two VNFs connected
 780 in series. Additional TestSteps will deploy a 3rd VNF and connect it in parallel to
 781 already configured VNFs. Traffic generator is instructed (by Multistream feature) to send
 782 two separate traffic streams. One stream will be sent to the standalone VNF and second
 783 to two chained VNFs.
 784
 785 In case, that test is defined as a performance test, then traffic results will be collected
 786 and available in both csv and rst report files.
 787
 788 .. code-block:: python
 789
 790     {
 791         "Name": "pvvp_pvp_cont",
 792         "Deployment": "pvvp",
 793         "Description": "PVVP and PVP in parallel with Continuous Stream",
 794         "Parameters" : {
 795             "TRAFFIC" : {
 796                 "traffic_type" : "rfc2544_continuous",
 797                 "multistream": 2,
 798             },
 799         },
 800         "TestSteps": [
 801                         ['vswitch', 'add_vport', '$VSWITCH_BRIDGE_NAME'],
 802                         ['vswitch', 'add_vport', '$VSWITCH_BRIDGE_NAME'],
 803                         # priority must be higher than default 32768, otherwise flows won't match
 804                         ['vswitch', 'add_flow', '$VSWITCH_BRIDGE_NAME',
 805                          {'in_port': '1', 'actions': ['output:#STEP[-2][1]'], 'idle_timeout': '0', 'dl_type':'0x0800',
 806                                                       'nw_proto':'17', 'tp_dst':'0', 'priority': '33000'}],
 807                         ['vswitch', 'add_flow', '$VSWITCH_BRIDGE_NAME',
 808                          {'in_port': '2', 'actions': ['output:#STEP[-2][1]'], 'idle_timeout': '0', 'dl_type':'0x0800',
 809                                                       'nw_proto':'17', 'tp_dst':'0', 'priority': '33000'}],
 810                         ['vswitch', 'add_flow', '$VSWITCH_BRIDGE_NAME', {'in_port': '#STEP[-4][1]', 'actions': ['output:1'],
 811                                                         'idle_timeout': '0'}],
 812                         ['vswitch', 'add_flow', '$VSWITCH_BRIDGE_NAME', {'in_port': '#STEP[-4][1]', 'actions': ['output:2'],
 813                                                         'idle_timeout': '0'}],
 814                         ['vswitch', 'dump_flows', '$VSWITCH_BRIDGE_NAME'],
 815                         ['vnf1', 'start'],
 816                      ]
 817     },
 818
 819 To run the test:
 820
 821   .. code-block:: console
 822
 823     ./vsperf --conf-file user_settings.py pvvp_pvp_cont
 824