test/test_infra.md

   1 # VPP Functional Test Infra
   2
   3 ## Running VPP tests
   4 VPP functional tests are triggered by `make test` command run in the git vpp source directory. Following Linux environment variables are used by the current VPP functional test infrastructure:
   5
   6 - `TEST=<name>` - run only specific test identified by filename `test/test_<name>.py`
   7 -  `V=[0|1|2]` - set verbosity level. `0` for minimal verbosity, `1` for increased verbosity, `2` for maximum verbosity. Default value is 0.
   8
   9 Example of running tests:
  10
  11 ```
  12 ~/src/vpp-test-infra$ make test V=1 TEST=vxlan
  13 ```
  14
  15 All tests listed in `test/` directory are run by default. To run selected tests you can set variable TEST when starting tests.
  16
  17 ## Overview
  18 The main functionality of the test framework is defined in [framework.py](test/framework.py) file. The implementation of the test framework uses classes and methods from Python module *unittest*.
  19
  20 Three main classes are defined to support the overall test automation:
  21
  22 * **class VppTestCase(unittest.TestCase)** - a sub-class of *unittest.TestCase* class. Provides methods to create and run test case. These methods can be divided into 5 groups:
  23     1. Methods to control test case setup and tear down:
  24         * *def setUpConstants(cls):*
  25         * *def setUpClass(cls):*
  26         * *def quit(cls):*
  27         * *def tearDownClass(cls):*
  28         * *def tearDown(self):*
  29         * *def setUp(self):*
  30
  31     2. Methods to create VPP packet generator interfaces:
  32         * *def create_interfaces(cls, args):*
  33
  34     3. Methods to execute VPP commands and print logs in the output (terminal for now):
  35         * *def log(cls, s, v=1):*
  36         * *def api(cls, s):*
  37         * *def cli(cls, v, s):*
  38
  39     4. Methods to control packet stream generation and capturing:
  40         * *def pg_add_stream(cls, i, pkts):*
  41         * *def pg_enable_capture(cls, args):*
  42         * *def pg_start(cls):*
  43         * *def pg_get_capture(cls, o):*
  44
  45     5. Methods to create and verify packets:
  46         * *def extend_packet(packet, size):*
  47         * *def add_packet_info_to_list(self, info):*
  48         * *def create_packet_info(self, pg_id, target_id):*
  49         * *def info_to_payload(info):*
  50         * *def payload_to_info(payload):*
  51         * *def get_next_packet_info(self, info):*
  52         * *def get_next_packet_info_for_interface(self, src_pg, info):*
  53         * *def get_next_packet_info_for_interface2(self, src_pg, dst_pg, info):*
  54
  55 * **class VppTestResult(unittest.TestResult)** - a sub-class of *unittest.TestResult* class. Provides methods to compile information about the tests that have succeeded and the ones that have failed. These methods can be divided into 4 groups:
  56     1. Processing test case result:
  57         * *def addSuccess(self, test):*
  58         * *def addFailure(self, test, err):*
  59         * *def addError(self, test, err):*
  60
  61     2. Processing test case description:
  62         * *def getDescription(self, test):*
  63
  64     3. Processing test case start and stop:
  65         * *def startTest(self, test):*
  66         * *def stopTest(self, test):*
  67
  68     4. Printing error and failure information:
  69         * *def printErrors(self):*
  70         * *def printErrorList(self, flavour, errors):*
  71
  72 * **class VppTestRunner(unittest.TextTestRunner)** - a sub-class of *unittest.TextTestRunner* class. Provides basic test runner implementation that prints results on standard error stream. Contains one method:
  73     * *def run(self, test):*
  74
  75 In addition [util.py] (test/util.py) file defines number of common methods useful for many test cases. All of these methods are currently contained in one class:
  76
  77 * **class Util(object)**:
  78     * *def resolve_arp(cls, args):*
  79     * *def resolve_icmpv6_nd(cls, args):*
  80     * *def config_ip4(cls, args):*
  81     * *def config_ip6(cls, args):*
  82
  83 ## Interaction with VPP
  84 VPP is started from command line as a sub-process during the test case setup phase. Command line attributes to start VPP are stored in class variable *vpp_cmdline*.
  85 To get an overview of VPP command line attributes, visit section [Command-line Arguments](https://wiki.fd.io/view/VPP/Command-line_Arguments) on VPP wiki page.
  86
  87 Current VPP test infrastructure is using two ways to interact with VPP for configuration, operational status check, tracing and logging.
  88
  89 ### Using API commands
  90 API commands are executed by VPP API test tool that is started from command line as a sub-process. Command line attributes to start VPP API test tool are stored in class variable *vpp_api_test_cmdline*.
  91 When executed, API command and its possible output are printed in the terminal if verbosity level is greater then 0.
  92
  93 Example:
  94
  95 ```
  96 cls.api("sw_interface_set_flags pg1 admin-up")
  97 ```
  98
  99 will print in the terminal
 100
 101 ```
 102 API: sw_interface_set_flags pg1 admin-up
 103 ```
 104
 105 ### Using CLI commands
 106 CLI commands are executed via VPP API test tool by sending API command "*exec + cli_command*". It is possible to set verbosity level for executing specific CLI commands, so that the CLI command is executed only and only if its associated verbosity level is equal or lower then the verbosity level set in the system.
 107
 108 Similarly to API commands, when executed, CLI command and its possible output are printed in the terminal if verbosity level is greater then 0.
 109
 110 Example I - CLI command will be executed always (its verbosity is 0):
 111
 112 ```
 113 cls.cli(0, "show l2fib")
 114 ```
 115
 116 Example II - CLI command will be executed only if the verbosity level is set to 2:
 117
 118 ```
 119 self.cli(2, "show l2fib verbose")
 120 ```
 121
 122 ## Logging
 123 It is possible to log some additional information in the terminal for different verbosity levels.
 124
 125 Example I - verbosity level of the log is set to default value (0):
 126
 127 ```
 128 self.log("Verifying capture %u" % i)
 129 ```
 130
 131 will be always printed in the terminal:
 132
 133 ```
 134 LOG: Verifying capture 0
 135 ```
 136
 137 Example II - the log will be printed in the terminal only if the verbosity level is set to 2:
 138
 139 ```
 140 self.log("Got packet on port %u: src=%u (id=%u)"
 141                          % (o, payload_info.src, payload_info.index), 2)
 142 ```
 143
 144 ---
 145 ***END***