docs/testing/developer/devguide/dev-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 ***********************
   5 Testing developer guide
   6 ***********************
   7
   8 .. toctree::
   9    :numbered:
  10    :maxdepth: 2
  11
  12
  13 ============
  14 Introduction
  15 ============
  16
  17 The goal of this guide consists in providing some guidelines for new developers
  18 involved in test areas.
  19
  20
  21 =================
  22 Developer journey
  23 =================
  24
  25 There are several ways to join test projects as a developer. In fact you may:
  26
  27  * Develop new test cases
  28  * Develop frameworks
  29  * Develop tooling (reporting, dashboards, graphs, middleware,...)
  30  * Troubleshoot results
  31  * Post-process results
  32
  33 These different tasks may be done within a specific project or as a shared
  34 resource accross the different projects.
  35
  36 If you develop new test cases, the best practice is to contribute upstream as
  37 much as possible. You may contact the testing group to know which project - in
  38 Anuket or upstream - would be the best place to host the test cases. Such
  39 contributions are usually directly connected to a specific project, more details
  40 can be found in the user guides of the testing projects.
  41
  42 Each Anuket testing project provides test cases and the framework to manage them.
  43 As a developer, you can obviously contribute to them. The developer guide of
  44 the testing projects shall indicate the procedure to follow.
  45
  46 Tooling may be specific to a project or generic to all the projects. For
  47 specific tooling, please report to the test project user guide. The tooling used
  48 by several test projects will be detailed in this document.
  49
  50 The best event to meet the testing community is probably the plugfest. Such an
  51 event is organized after each release. Most of the test projects are present.
  52
  53 The summit is also a good opportunity to meet most of the actors `[DEV4]`_.
  54
  55
  56 Best practices
  57 ==============
  58
  59 All the test projects do not have the same maturity and/or number of
  60 contributors. The nature of the test projects may be also different. The
  61 following best practices may not be acurate for all the projects and are only
  62 indicative. Contact the testing group for further details.
  63
  64
  65 Repository structure
  66 --------------------
  67
  68 Most of the projects have a similar structure, which can be defined as follows::
  69
  70   `-- home
  71     |-- requirements.txt
  72     |-- setup.py
  73     |-- tox.ini
  74     |
  75     |-- <project>
  76     |       |-- <api>
  77     |       |-- <framework>
  78     |       `-- <test cases>
  79     |
  80     |-- docker
  81     |     |-- Dockerfile
  82     |     `-- Dockerfile.aarch64.patch
  83     |-- <unit tests>
  84     `- docs
  85        |-- release
  86        |   |-- release-notes
  87        |   `-- results
  88        `-- testing
  89            |-- developer
  90            |     `-- devguide
  91            |-- user
  92                  `-- userguide
  93
  94
  95 API
  96 ---
  97 Test projects are installing tools and triggering tests. When it is possible it
  98 is recommended to implement an API in order to perform the different actions.
  99
 100 Each test project should be able to expose and consume APIs from other test
 101 projects. This pseudo micro service approach should allow a flexible use of
 102 the different projects and reduce the risk of overlapping. In fact if project A
 103 provides an API to deploy a traffic generator, it is better to reuse it rather
 104 than implementing a new way to deploy it. This approach has not been implemented
 105 yet but the prerequisites consiting in exposing and API has already been done by
 106 several test projects.
 107
 108
 109 CLI
 110 ---
 111 Most of the test projects provide a docker as deliverable. Once connected, it is
 112 possible to prepare the environement and run tests through a CLI.
 113
 114
 115 Dockerization
 116 -------------
 117 Dockerization has been introduced in Brahmaputra and adopted by most of the test
 118 projects.
 119
 120 Code quality
 121 ------------
 122
 123 It is recommended to control the quality of the code of the testing projects,
 124 and more precisely to implement some verifications before any merge:
 125
 126 * pep8
 127 * pylint
 128 * unit tests
 129
 130 The code of the test project must be covered by unit tests. The coverage
 131 shall be reasonable and not decrease when adding new features to the framework.
 132 The use of tox is recommended.
 133 It is possible to implement strict rules (no decrease of pylint score, unit
 134 test coverages) on critical python classes.
 135
 136
 137 Third party tooling
 138 -------------------
 139
 140 Several test projects integrate third party tooling for code quality check
 141 and/or traffic generation. Some of the tools can be listed as follows:
 142
 143 +---------------+----------------------+------------------------------------+
 144 | Project       | Tool                 | Comments                           |
 145 +===============+======================+====================================+
 146 | Functest      | Tempest              | OpenStack test tooling             |
 147 |               | Rally                | OpenStack test tooling             |
 148 |               | Refstack             | OpenStack test tooling             |
 149 |               | RobotFramework       | Used for ODL tests                 |
 150 +---------------+----------------------+------------------------------------+
 151 | VSPERF        | TODO                 |                                    |
 152 +---------------+----------------------+------------------------------------+
 153
 154
 155 ======================================
 156 Testing group configuration parameters
 157 ======================================
 158
 159 Testing categories
 160 ==================
 161
 162 The testing group defined several categories also known as tiers. These
 163 categories can be used to group test suites.
 164
 165 +----------------+-------------------------------------------------------------+
 166 | Category       | Description                                                 |
 167 +================+=============================================================+
 168 | Healthcheck    | Simple and quick healthcheck tests case                     |
 169 +----------------+-------------------------------------------------------------+
 170 | Smoke          | Set of smoke test cases/suites to validate the release      |
 171 +----------------+-------------------------------------------------------------+
 172 | Features       | Test cases that validate a specific feature on top of Anuket|
 173 |                | Those come from Feature projects and need a bit of support  |
 174 |                | for integration                                             |
 175 +----------------+-------------------------------------------------------------+
 176 | Components     | Tests on a specific component (e.g. OpenStack, OVS, DPDK,..)|
 177 |                | It may extend smoke tests                                   |
 178 +----------------+-------------------------------------------------------------+
 179 | Performance    | Performance qualification                                   |
 180 +----------------+-------------------------------------------------------------+
 181 | VNF            | Test cases related to deploy an open source VNF including   |
 182 |                | an orchestrator                                             |
 183 +----------------+-------------------------------------------------------------+
 184 | Stress         | Stress and robustness tests                                 |
 185 +----------------+-------------------------------------------------------------+
 186 | In Service     | In service testing                                          |
 187 +----------------+-------------------------------------------------------------+
 188
 189 Testing domains
 190 ===============
 191
 192 The domains deal with the technical scope of the tests. It shall correspond to
 193 domains defined for the certification program:
 194
 195  * compute
 196  * network
 197  * storage
 198  * hypervisor
 199  * container
 200  * vim
 201  * mano
 202  * vnf
 203  * ...
 204
 205 Testing coverage
 206 =================
 207 One of the goals of the testing working group is to identify the poorly covered
 208 areas and avoid testing overlap.
 209 Ideally based on the declaration of the test cases, through the tags, domains
 210 and tier fields, it shall be possible to create heuristic maps.
 211
 212 =============================================
 213 Reliability, Stress and Long Duration Testing
 214 =============================================
 215
 216 Resiliency of NFV refers to the ability of the NFV framework to limit disruption
 217 and return to normal or at a minimum acceptable service delivery level in the
 218 face of a fault, failure, or an event that disrupts the normal operation
 219 `[DEV5]`_.
 220
 221 **Reliability** testing evaluates the ability of SUT to recover in face of fault,
 222 failure or disrupts in normal operation or simply the ability of SUT absorbing
 223 "disruptions".
 224
 225 Reliability tests use different forms of faults as stimulus, and the test must
 226 measure the reaction in terms of the outage time or impairments to transmission.
 227
 228 **Stress testing** involves producing excess load as stimulus, and the test
 229 must measure the reaction in terms of unexpected outages or (more likely)
 230 impairments to transmission.
 231
 232 These kinds of "load" will cause "disruption" which could be easily found in
 233 system logs. It is the purpose to raise such "load" to evaluate the SUT if it
 234 could provide an acceptable level of service or level of confidence during such
 235 circumstances.
 236
 237
 238 =======
 239 How TOs
 240 =======
 241
 242 How can I contribute to a test project?
 243 =======================================
 244 As any project, the best solution is to contact the project. The project
 245 members with their email address can be found under
 246 https://git.opnfv.org/<project>/tree/INFO
 247
 248 How do I integrate my tests in CI?
 249 ==================================
 250 It shall be discussed directly with the project you are working with. It is
 251 done through jenkins jobs calling testing project files but the way to onboard
 252 cases differ from one project to another.
 253
 254 How to declare my tests in the test Database?
 255 =============================================
 256 If you have access to the test API swagger (access granted to contributors), you
 257 may use the swagger interface of the test API to declare your project.
 258 The URL is http://testresults.opnfv.org/test/swagger/spec.html.
 259
 260 .. figure:: ../../../images/swaggerUI.png
 261    :align: center
 262    :alt: Testing Group Test API swagger
 263
 264 Click on *Spec*, the list of available methods must be displayed.
 265
 266 .. figure:: ../../../images/API-operations.png
 267    :align: center
 268    :alt: Testing Group Test API swagger
 269
 270 For the declaration of a new project use the POST /api/v1/projects method.
 271
 272 For the declaration of new test cases in an existing project, use the POST
 273 /api/v1/projects/{project_name}/cases method
 274
 275  .. figure:: ../../../images/CreateCase.png
 276     :align: center
 277     :alt: Testing group declare new test case
 278
 279 How to push your results into the Test Database?
 280 ================================================
 281
 282 The test database is used to collect test results. By default it is
 283 enabled only for CI tests from Production CI pods.
 284
 285 Please note that it is possible to create your own local database.
 286
 287 A dedicated database is for instance created for each plugfest.
 288
 289 The architecture and associated API is described in previous chapter.
 290 If you want to push your results from CI, you just have to call the API
 291 at the end of your script.
 292
 293
 294 Where can I find the documentation on the test API?
 295 ===================================================
 296
 297 The Test API is now documented in this document (see sections above).
 298 You may also find autogenerated documentation in
 299 http://artifacts.opnfv.org/releng/docs/testapi.html
 300
 301 I have tests, to which category should I declare them?
 302 ======================================================
 303 See table above.
 304
 305 The main ambiguity could be between features and VNF.
 306 In fact sometimes you have to spawn VMs to demonstrate the capabilities of the
 307 feature you introduced.
 308 We recommend to declare your test in the feature category.
 309
 310 VNF category is really dedicated to test including:
 311
 312  * creation of resources
 313  * deployement of an orchestrator/VNFM
 314  * deployment of the VNF
 315  * test of the VNFM
 316  * free resources
 317
 318 The goal is not to study a particular feature on the infrastructure but to have
 319 a whole end to end test of a VNF automatically deployed in CI.
 320 Moreover VNF are run in weekly jobs (one a week), feature tests are in daily
 321 jobs and use to get a scenario score.
 322
 323 Where are the logs of CI runs?
 324 ==============================
 325
 326 Logs and configuration files can be pushed to artifact server from the CI under
 327 http://artifacts.opnfv.org/<project name>
 328
 329
 330 ==========
 331 References
 332 ==========
 333
 334 `[DEV4]`_: Conversation with the testing community, OPNFV Beijing Summit
 335
 336 `[DEV5]`_: GS NFV 003
 337
 338 .. _`[DEV4]`: https://www.youtube.com/watch?v=f9VAUdEqHoA
 339 .. _`[DEV5]`: http://www.etsi.org/deliver/etsi_gs/NFV/001_099/003/01.01.01_60/gs_NFV003v010101p.pdf