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 OPNFV testing ecosystem is wide.
  18
  19 The goal of this guide consists in providing some guidelines for new developers
  20 involved in test areas.
  21
  22 For the description of the ecosystem, see `[DEV1]`_.
  23
  24 =================
  25 Developer journey
  26 =================
  27
  28 There are several ways to join test projects as a developer. In fact you may:
  29
  30  * Develop new test cases
  31  * Develop frameworks
  32  * Develop tooling (reporting, dashboards, graphs, middleware,...)
  33  * Troubleshoot results
  34  * Post-process results
  35
  36 These different tasks may be done within a specific project or as a shared
  37 resource accross the different projects.
  38
  39 If you develop new test cases, the best practice is to contribute upstream as
  40 much as possible. You may contact the testing group to know which project - in
  41 OPNFV or upstream - would be the best place to host the test cases. Such
  42 contributions are usually directly connected to a specific project, more details
  43 can be found in the user guides of the testing projects.
  44
  45 Each OPNFV testing project provides test cases and the framework to manage them.
  46 As a developer, you can obviously contribute to them. The developer guide of
  47 the testing projects shall indicate the procedure to follow.
  48
  49 Tooling may be specific to a project or generic to all the projects. For
  50 specific tooling, please report to the test project user guide. The tooling used
  51 by several test projects will be detailed in this document.
  52
  53 The best event to meet the testing community is probably the plugfest. Such an
  54 event is organized after each release. Most of the test projects are present.
  55
  56 The summit is also a good opportunity to meet most of the actors `[DEV4]`_.
  57
  58 Be involved in the testing group
  59 ================================
  60
  61 The testing group is a self organized working group. The OPNFV projects dealing
  62 with testing are invited to participate in order to elaborate and consolidate a
  63 consistant test strategy (test case definition, scope of projects, resources for
  64 long duration, documentation, ...) and align tooling or best practices.
  65
  66 A weekly meeting is organized, the agenda may be amended by any participant.
  67 2 slots have been defined (US/Europe and APAC). Agendas and minutes are public.
  68 See `[DEV3]`_ for details.
  69 The testing group IRC channel is #opnfv-testperf
  70
  71 Best practices
  72 ==============
  73
  74 All the test projects do not have the same maturity and/or number of
  75 contributors. The nature of the test projects may be also different. The
  76 following best practices may not be acurate for all the projects and are only
  77 indicative. Contact the testing group for further details.
  78
  79
  80 Repository structure
  81 --------------------
  82
  83 Most of the projects have a similar structure, which can be defined as follows::
  84
  85   `-- home
  86     |-- requirements.txt
  87     |-- setup.py
  88     |-- tox.ini
  89     |
  90     |-- <project>
  91     |       |-- <api>
  92     |       |-- <framework>
  93     |       `-- <test cases>
  94     |
  95     |-- docker
  96     |     |-- Dockerfile
  97     |     `-- Dockerfile.aarch64.patch
  98     |-- <unit tests>
  99     `- docs
 100        |-- release
 101        |   |-- release-notes
 102        |   `-- results
 103        `-- testing
 104            |-- developer
 105            |     `-- devguide
 106            |-- user
 107                  `-- userguide
 108
 109
 110 API
 111 ---
 112 Test projects are installing tools and triggering tests. When it is possible it
 113 is recommended to implement an API in order to perform the different actions.
 114
 115 Each test project should be able to expose and consume APIs from other test
 116 projects. This pseudo micro service approach should allow a flexible use of
 117 the different projects and reduce the risk of overlapping. In fact if project A
 118 provides an API to deploy a traffic generator, it is better to reuse it rather
 119 than implementing a new way to deploy it. This approach has not been implemented
 120 yet but the prerequisites consiting in exposing and API has already been done by
 121 several test projects.
 122
 123
 124 CLI
 125 ---
 126 Most of the test projects provide a docker as deliverable. Once connected, it is
 127 possible to prepare the environement and run tests through a CLI.
 128
 129
 130 Dockerization
 131 -------------
 132 Dockerization has been introduced in Brahmaputra and adopted by most of the test
 133 projects. Docker containers are pulled on the jumphost of OPNFV POD.
 134 <TODO Jose/Mark/Alec>
 135
 136 Code quality
 137 ------------
 138
 139 It is recommended to control the quality of the code of the testing projects,
 140 and more precisely to implement some verifications before any merge:
 141
 142 * pep8
 143 * pylint
 144 * unit tests (python 2.7)
 145 * unit tests (python 3.5)
 146
 147 The code of the test project must be covered by unit tests. The coverage
 148 shall be reasonable and not decrease when adding new features to the framework.
 149 The use of tox is recommended.
 150 It is possible to implement strict rules (no decrease of pylint score, unit
 151 test coverages) on critical python classes.
 152
 153
 154 Third party tooling
 155 -------------------
 156
 157 Several test projects integrate third party tooling for code quality check
 158 and/or traffic generation. Some of the tools can be listed as follows:
 159
 160 +---------------+----------------------+------------------------------------+
 161 | Project       | Tool                 | Comments                           |
 162 +===============+======================+====================================+
 163 | Bottlenecks   | TODO                 |                                    |
 164 +---------------+----------------------+------------------------------------+
 165 | Functest      | Tempest              | OpenStack test tooling             |
 166 |               | Rally                | OpenStack test tooling             |
 167 |               | Refstack             | OpenStack test tooling             |
 168 |               | RobotFramework       | Used for ODL tests                 |
 169 +---------------+----------------------+------------------------------------+
 170 | QTIP          | Unixbench            |                                    |
 171 |               | RAMSpeed             |                                    |
 172 |               | nDPI                 |                                    |
 173 |               | openSSL              |                                    |
 174 |               | inxi                 |                                    |
 175 +---------------+----------------------+------------------------------------+
 176 | Storperf      | TODO                 |                                    |
 177 +---------------+----------------------+------------------------------------+
 178 | VSPERF        | TODO                 |                                    |
 179 +---------------+----------------------+------------------------------------+
 180 | Yardstick     | Moongen              | Traffic generator                  |
 181 |               | Trex                 | Traffic generator                  |
 182 |               | Pktgen               | Traffic generator                  |
 183 |               | IxLoad, IxNet        | Traffic generator                  |
 184 |               | SPEC                 | Compute                            |
 185 |               | Unixbench            | Compute                            |
 186 |               | RAMSpeed             | Compute                            |
 187 |               | LMBench              | Compute                            |
 188 |               | Iperf3               | Network                            |
 189 |               | Netperf              | Network                            |
 190 |               | Pktgen-DPDK          | Network                            |
 191 |               | Testpmd              | Network                            |
 192 |               | L2fwd                | Network                            |
 193 |               | Fio                  | Storage                            |
 194 |               | Bonnie++             | Storage                            |
 195 +---------------+----------------------+------------------------------------+
 196
 197
 198 ======================================
 199 Testing group configuration parameters
 200 ======================================
 201
 202 Testing categories
 203 ==================
 204
 205 The testing group defined several categories also known as tiers. These
 206 categories can be used to group test suites.
 207
 208 +----------------+-------------------------------------------------------------+
 209 | Category       | Description                                                 |
 210 +================+=============================================================+
 211 | Healthcheck    | Simple and quick healthcheck tests case                     |
 212 +----------------+-------------------------------------------------------------+
 213 | Smoke          | Set of smoke test cases/suites to validate the release      |
 214 +----------------+-------------------------------------------------------------+
 215 | Features       | Test cases that validate a specific feature on top of OPNFV.|
 216 |                | Those come from Feature projects and need a bit of support  |
 217 |                | for integration                                             |
 218 +----------------+-------------------------------------------------------------+
 219 | Components     | Tests on a specific component (e.g. OpenStack, OVS, DPDK,..)|
 220 |                | It may extend smoke tests                                   |
 221 +----------------+-------------------------------------------------------------+
 222 | Performance    | Performance qualification                                   |
 223 +----------------+-------------------------------------------------------------+
 224 | VNF            | Test cases related to deploy an open source VNF including   |
 225 |                | an orchestrator                                             |
 226 +----------------+-------------------------------------------------------------+
 227 | Stress         | Stress and robustness tests                                 |
 228 +----------------+-------------------------------------------------------------+
 229 | In Service     | In service testing                                          |
 230 +----------------+-------------------------------------------------------------+
 231
 232 Testing domains
 233 ===============
 234
 235 The domains deal with the technical scope of the tests. It shall correspond to
 236 domains defined for the certification program:
 237
 238  * compute
 239  * network
 240  * storage
 241  * hypervisor
 242  * container
 243  * vim
 244  * mano
 245  * vnf
 246  * ...
 247
 248 Testing coverage
 249 =================
 250 One of the goals of the testing working group is to identify the poorly covered
 251 areas and avoid testing overlap.
 252 Ideally based on the declaration of the test cases, through the tags, domains
 253 and tier fields, it shall be possible to create heuristic maps.
 254
 255 =============================================
 256 Reliability, Stress and Long Duration Testing
 257 =============================================
 258
 259 Resiliency of NFV refers to the ability of the NFV framework to limit disruption
 260 and return to normal or at a minimum acceptable service delivery level in the
 261 face of a fault, failure, or an event that disrupts the normal operation
 262 `[DEV5]`_.
 263
 264 **Reliability** testing evaluates the ability of SUT to recover in face of fault,
 265 failure or disrupts in normal operation or simply the ability of SUT absorbing
 266 "disruptions".
 267
 268 Reliability tests use different forms of faults as stimulus, and the test must
 269 measure the reaction in terms of the outage time or impairments to transmission.
 270
 271 **Stress testing** involves producing excess load as stimulus, and the test
 272 must measure the reaction in terms of unexpected outages or (more likely)
 273 impairments to transmission.
 274
 275 These kinds of "load" will cause "disruption" which could be easily found in
 276 system logs. It is the purpose to raise such "load" to evaluate the SUT if it
 277 could provide an acceptable level of service or level of confidence during such
 278 circumstances. In Danube and Euphrates, we only considered the stress test with
 279 excess load over OPNFV Platform.
 280
 281 In Danube, Bottlenecks and Yardstick project jointly implemented 2 stress tests
 282 (concurrently create/destroy VM pairs and do ping, system throughput limit)
 283 while Bottlenecks acts as the load manager calling yardstick to execute each
 284 test iteration. These tests are designed to test for breaking points and provide
 285 level of confidence of the system to users. Summary of the test cases are listed
 286 in the following addresses:
 287
 288   * https://wiki.opnfv.org/display/bottlenecks/Stress+Testing+over+OPNFV+Platform
 289   * https://wiki.opnfv.org/download/attachments/2926539/Testing%20over%20Long%20Duration%20POD.pptx?version=2&modificationDate=1502943821000&api=v2
 290
 291 **Stress test cases** for OPNFV Euphrates (OS Ocata) release can be seen as
 292 extension/enhancement of those in D release. These tests are located in
 293 Bottlenecks/Yardstick repo (Bottlenecks as load manager while Yardstick execute
 294 each test iteration):
 295
 296   * VNF scale out/up tests (also plan to measure storage usage simultaneously): https://wiki.opnfv.org/pages/viewpage.action?pageId=12390101
 297   * Life-cycle event with throughputs (measure NFVI to support concurrent
 298     network usage from different VM pairs):
 299     https://wiki.opnfv.org/display/DEV/Intern+Project%3A+Baseline+Stress+Test+Case+for+Bottlenecks+E+Release
 300
 301 In OPNFV E release, we also plan to do **long duration testing** over OS Ocata.
 302 A separate CI pipe testing OPNFV XCI (OSA) is proposed to accomplish the job.
 303 We have applied specific pod for the testing.
 304 Proposals and details are listed below:
 305
 306 * https://wiki.opnfv.org/display/testing/Euphrates+Testing+needs
 307 * https://wiki.opnfv.org/download/attachments/2926539/testing%20evolution%20v1_4.pptx?version=1&modificationDate=1503937629000&api=v2
 308 * https://wiki.opnfv.org/download/attachments/2926539/Testing%20over%20Long%20Duration%20POD.pptx?version=2&modificationDate=1502943821000&api=v2
 309
 310 The long duration testing is supposed to be started when OPNFV E release is
 311 published.
 312 A simple monitoring module for these tests is also planned to be added:
 313 https://wiki.opnfv.org/display/DEV/Intern+Project%3A+Monitoring+Stress+Testing+for+Bottlenecks+E+Release
 314
 315
 316 =======
 317 How TOs
 318 =======
 319
 320 Where can I find information on the different test projects?
 321 ============================================================
 322 On http://docs.opnfv.org! A section is dedicated to the testing projects. You
 323 will find the overview of the ecosystem and the links to the project documents.
 324
 325 Another source is the testing wiki on https://wiki.opnfv.org/display/testing
 326
 327 You may also contact the testing group on the IRC channel #opnfv-testperf or by
 328 mail at test-wg AT lists.opnfv.org (testing group) or opnfv-tech-discuss AT
 329 lists.opnfv.org (generic technical discussions).
 330
 331
 332 How can I contribute to a test project?
 333 =======================================
 334 As any project, the best solution is to contact the project. The project
 335 members with their email address can be found under
 336 https://git.opnfv.org/<project>/tree/INFO
 337
 338 You may also send a mail to the testing mailing list or use the IRC channel
 339 #opnfv-testperf
 340
 341
 342 Where can I find hardware resources?
 343 ====================================
 344 You should discuss this topic with the project you are working with. If you need
 345 access to an OPNFV community POD, it is possible to contact the infrastructure
 346 group. Depending on your needs (scenario/installer/tooling), it should be
 347 possible to find free time slots on one OPNFV community POD from the Pharos
 348 federation. Create a JIRA ticket to describe your needs on
 349 https://jira.opnfv.org/projects/INFRA.
 350 You must already be an OPNFV contributor. See
 351 https://wiki.opnfv.org/display/DEV/Developer+Getting+Started.
 352
 353 Please note that lots of projects have their own "how to contribute" or
 354 "get started" page on the OPNFV wiki.
 355
 356
 357 How do I integrate my tests in CI?
 358 ==================================
 359 It shall be discussed directly with the project you are working with. It is
 360 done through jenkins jobs calling testing project files but the way to onboard
 361 cases differ from one project to another.
 362
 363 How to declare my tests in the test Database?
 364 =============================================
 365 If you have access to the test API swagger (access granted to contributors), you
 366 may use the swagger interface of the test API to declare your project.
 367 The URL is http://testresults.opnfv.org/test/swagger/spec.html.
 368
 369 .. figure:: ../../../images/swaggerUI.png
 370    :align: center
 371    :alt: Testing Group Test API swagger
 372
 373 Click on *Spec*, the list of available methods must be displayed.
 374
 375 .. figure:: ../../../images/API-operations.png
 376    :align: center
 377    :alt: Testing Group Test API swagger
 378
 379 For the declaration of a new project use the POST /api/v1/projects method.
 380
 381 For the declaration of new test cases in an existing project, use the POST
 382 /api/v1/projects/{project_name}/cases method
 383
 384  .. figure:: ../../../images/CreateCase.png
 385     :align: center
 386     :alt: Testing group declare new test case
 387
 388 How to push your results into the Test Database?
 389 ================================================
 390
 391 The test database is used to collect test results. By default it is
 392 enabled only for CI tests from Production CI pods.
 393
 394 Please note that it is possible to create your own local database.
 395
 396 A dedicated database is for instance created for each plugfest.
 397
 398 The architecture and associated API is described in previous chapter.
 399 If you want to push your results from CI, you just have to call the API
 400 at the end of your script.
 401
 402 You can also reuse a python function defined in functest_utils.py `[DEV2]`_
 403
 404
 405 Where can I find the documentation on the test API?
 406 ===================================================
 407
 408 The Test API is now documented in this document (see sections above).
 409 You may also find autogenerated documentation in
 410 http://artifacts.opnfv.org/releng/docs/testapi.html
 411 A web protal is also under construction for certification at
 412 http://testresults.opnfv.org/test/#/
 413
 414 I have tests, to which category should I declare them?
 415 ======================================================
 416 See table above.
 417
 418 The main ambiguity could be between features and VNF.
 419 In fact sometimes you have to spawn VMs to demonstrate the capabilities of the
 420 feature you introduced.
 421 We recommend to declare your test in the feature category.
 422
 423 VNF category is really dedicated to test including:
 424
 425  * creation of resources
 426  * deployement of an orchestrator/VNFM
 427  * deployment of the VNF
 428  * test of the VNFM
 429  * free resources
 430
 431 The goal is not to study a particular feature on the infrastructure but to have
 432 a whole end to end test of a VNF automatically deployed in CI.
 433 Moreover VNF are run in weekly jobs (one a week), feature tests are in daily
 434 jobs and use to get a scenario score.
 435
 436 Where are the logs of CI runs?
 437 ==============================
 438
 439 Logs and configuration files can be pushed to artifact server from the CI under
 440 http://artifacts.opnfv.org/<project name>
 441
 442
 443 ==========
 444 References
 445 ==========
 446
 447 `[DEV1]`_: OPNFV Testing Ecosystem
 448
 449 `[DEV2]`_: Python code sample to push results into the Database
 450
 451 `[DEV3]`_: Testing group wiki page
 452
 453 `[DEV4]`_: Conversation with the testing community, OPNFV Beijing Summit
 454
 455 `[DEV5]`_: GS NFV 003
 456
 457 .. _`[DEV1]`: http://docs.opnfv.org/en/latest/testing/ecosystem/index.html
 458 .. _`[DEV2]`: https://git.opnfv.org/functest/tree/functest/utils/functest_utils.py#176
 459 .. _`[DEV3]`: https://wiki.opnfv.org/display/meetings/Test+Working+Group+Weekly+Meeting
 460 .. _`[DEV4]`: https://www.youtube.com/watch?v=f9VAUdEqHoA
 461 .. _`[DEV5]`: http://www.etsi.org/deliver/etsi_gs/NFV/001_099/003/01.01.01_60/gs_NFV003v010101p.pdf
 462
 463 IRC support chan: #opnfv-testperf