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