docs/report/csit_framework_documentation/csit_design.rst

   1 .. _csit-design:
   2
   3 Design
   4 ======
   5
   6 FD.io CSIT system design needs to meet continuously expanding
   7 requirements of FD.io projects including VPP, related sub-systems (e.g.
   8 plugin applications, DPDK drivers) and FD.io applications (e.g. DPDK
   9 applications), as well as growing number of compute platforms running
  10 those applications. With CSIT project scope and charter including both
  11 FD.io continuous testing AND performance trending/comparisons, those
  12 evolving requirements further amplify the need for CSIT framework
  13 modularity, flexibility and usability.
  14
  15 Design Hierarchy
  16 ----------------
  17
  18 CSIT follows a hierarchical system design with SUTs and DUTs at the
  19 bottom level of the hierarchy, presentation level at the top level and a
  20 number of functional layers in-between. The current CSIT system design
  21 including CSIT framework is depicted in the figure below.
  22
  23 .. only:: latex
  24
  25     .. raw:: latex
  26
  27         \begin{figure}[H]
  28             \centering
  29                 \graphicspath{{../_tmp/src/csit_framework_documentation/}}
  30                 \includegraphics[width=0.90\textwidth]{csit_design_picture}
  31                 \label{fig:csit_design_picture}
  32         \end{figure}
  33
  34 .. only:: html
  35
  36     .. figure:: csit_design_picture.svg
  37         :alt: FD.io CSIT system design
  38         :align: center
  39
  40    *FD.io CSIT system design*
  41
  42 A brief bottom-up description is provided here:
  43
  44 #. SUTs, DUTs, TGs
  45
  46    - SUTs - Systems Under Test;
  47    - DUTs - Devices Under Test;
  48    - TGs - Traffic Generators;
  49
  50 #. Level-1 libraries - Robot and Python
  51
  52    - Lowest level CSIT libraries abstracting underlying test environment, SUT,
  53      DUT and TG specifics;
  54    - Used commonly across multiple L2 KWs;
  55    - Performance and functional tests:
  56
  57      - L1 KWs (KeyWords) are implemented as RF libraries and Python
  58        libraries;
  59
  60    - Performance TG L1 KWs:
  61
  62      - All L1 KWs are implemented as Python libraries:
  63
  64        - Support for TRex only today;
  65        - CSIT IXIA drivers in progress;
  66
  67    - Performance data plane traffic profiles:
  68
  69      - TG-specific stream profiles provide full control of:
  70
  71        - Packet definition – layers, MACs, IPs, ports, combinations thereof
  72          e.g. IPs and UDP ports;
  73        - Stream definitions - different streams can run together, delayed,
  74          one after each other;
  75        - Stream profiles are independent of CSIT framework and can be used
  76          in any T-rex setup, can be sent anywhere to repeat tests with
  77          exactly the same setup;
  78        - Easily extensible – one can create a new stream profile that meets
  79          tests requirements;
  80        - Same stream profile can be used for different tests with the same
  81          traffic needs;
  82
  83    - Functional data plane traffic scripts:
  84
  85      - Scapy specific traffic scripts;
  86
  87 #. Level-2 libraries - Robot resource files:
  88
  89    - Higher level CSIT libraries abstracting required functions for executing
  90      tests;
  91    - L2 KWs are classified into the following functional categories:
  92
  93      - Configuration, test, verification, state report;
  94      - Suite setup, suite teardown;
  95      - Test setup, test teardown;
  96
  97 #. Tests - Robot:
  98
  99    - Test suites with test cases;
 100    - Functional tests using VIRL environment:
 101
 102      - VPP;
 103      - Honeycomb;
 104      - NSH_SFC;
 105
 106    - Performance tests using physical testbed environment:
 107
 108      - VPP;
 109      - DPDK-Testpmd;
 110      - DPDK-L3Fwd;
 111      - Honeycomb;
 112      - VPP Container K8s orchestrated topologies;
 113
 114    - Tools:
 115
 116      - Documentation generator;
 117      - Report generator;
 118      - Testbed environment setup ansible playbooks;
 119      - Operational debugging scripts;
 120
 121 Test Lifecycle Abstraction
 122 --------------------------
 123
 124 A well coded test must follow a disciplined abstraction of the test
 125 lifecycles that includes setup, configuration, test and verification. In
 126 addition to improve test execution efficiency, the commmon aspects of
 127 test setup and configuration shared across multiple test cases should be
 128 done only once. Translating these high-level guidelines into the Robot
 129 Framework one arrives to definition of a well coded RF tests for FD.io
 130 CSIT. Anatomy of Good Tests for CSIT:
 131
 132 #. Suite Setup - Suite startup Configuration common to all Test Cases in suite:
 133    uses Configuration KWs, Verification KWs, StateReport KWs;
 134 #. Test Setup - Test startup Configuration common to multiple Test Cases: uses
 135    Configuration KWs, StateReport KWs;
 136 #. Test Case - uses L2 KWs with RF Gherkin style:
 137
 138    - prefixed with {Given} - Verification of Test setup, reading state: uses
 139      Configuration KWs, Verification KWs, StateReport KWs;
 140    - prefixed with {When} - Test execution: Configuration KWs, Test KWs;
 141    - prefixed with {Then} - Verification of Test execution, reading state: uses
 142      Verification KWs, StateReport KWs;
 143
 144 #. Test Teardown - post Test teardown with Configuration cleanup and
 145    Verification common to multiple Test Cases - uses: Configuration KWs,
 146    Verification KWs, StateReport KWs;
 147 #. Suite Teardown - Suite post-test Configuration cleanup: uses Configuration
 148    KWs, Verification KWs, StateReport KWs;
 149
 150 RF Keywords Functional Classification
 151 -------------------------------------
 152
 153 CSIT RF KWs are classified into the functional categories matching the test
 154 lifecycle events described earlier. All CSIT RF L2 and L1 KWs have been grouped
 155 into the following functional categories:
 156
 157 #. Configuration;
 158 #. Test;
 159 #. Verification;
 160 #. StateReport;
 161 #. SuiteSetup;
 162 #. TestSetup;
 163 #. SuiteTeardown;
 164 #. TestTeardown;
 165
 166 RF Keywords Naming Guidelines
 167 -----------------------------
 168
 169 Readability counts: "..code is read much more often than it is written."
 170 Hence following a good and consistent grammar practice is important when
 171 writing :abbr:`RF (Robot Framework)` KeyWords and Tests. All CSIT test cases
 172 are coded using Gherkin style and include only L2 KWs references. L2 KWs are
 173 coded using simple style and include L2 KWs, L1 KWs, and L1 python references.
 174 To improve readability, the proposal is to use the same grammar for both
 175 :abbr:`RF (Robot Framework)` KW styles, and to formalize the grammar of English
 176 sentences used for naming the :abbr:`RF (Robot Framework)` KWs. :abbr:`RF (Robot
 177 Framework)` KWs names are short sentences expressing functional description of
 178 the command. They must follow English sentence grammar in one of the following
 179 forms:
 180
 181 #. **Imperative** - verb-object(s): *"Do something"*, verb in base form.
 182 #. **Declarative** - subject–verb–object(s): *"Subject does something"*, verb in
 183    a third-person singular present tense form.
 184 #. **Affirmative** - modal_verb-verb-object(s): *"Subject should be something"*,
 185    *"Object should exist"*, verb in base form.
 186 #. **Negative** - modal_verb-Not-verb-object(s): *"Subject should not be
 187    something"*, *"Object should not exist"*, verb in base form.
 188
 189 Passive form MUST NOT be used. However a usage of past participle as an
 190 adjective is okay. See usage examples provided in the Coding guidelines
 191 section below. Following sections list applicability of the above
 192 grammar forms to different :abbr:`RF (Robot Framework)` KW categories. Usage
 193 examples are provided, both good and bad.
 194
 195 Coding Guidelines
 196 -----------------
 197
 198 Coding guidelines can be found on `Design optimizations wiki page
 199 <https://wiki.fd.io/view/CSIT/Design_Optimizations>`_.