docs/content/overview/csit/design.md

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