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 `[1]`_.
  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
  34 These different tasks may be done within a specific project or as a shared
  35 resource accross the different projects.
  36
  37 If you develop new test cases, the best practice is to contribute upstream as
  38 much as possible. You may contact the testing group to know which project - in
  39 OPNFV or upstream - would be the best place to host the test cases. Such
  40 contributions are usually directly connected to a specific project, more details
  41 can be found in the user guides of the testing projects.
  42
  43 Each OPNFV testing project provides test cases and the framework to manage them.
  44 As a developer, you can obviously contribute to them. The developer guide of
  45 the testing projects shall indicate the procedure to follow.
  46
  47 Tooling may be specific to a project or generic to all the projects. For
  48 specific tooling, please report to the test project user guide. The tooling used
  49 by several test projects will be detailed in this document.
  50
  51 Be involved in the testing group
  52 ================================
  53
  54 The testing group is a self organized working group. The OPNFV projects dealing
  55 with testing are invited to participate in order to elaborate and consolidate a
  56 consistant test strategy (test case definition, scope of projects, resources for
  57 long duration, documentation, ...) and align tooling or best practices.
  58
  59 A weekly meeting is organized, the agenda may be amended by any participant.
  60 2 slots have been defined (US and APAC). Agendas and minutes are public.See
  61 `[8]`_ for details.
  62 The testing group IRC channel is #opnfv-testperf
  63
  64 Best practices
  65 ==============
  66
  67 All the test projects do not have the same maturity and/or number of
  68 contributors. The nature of the test projects may be also different. The
  69 following best practices may not be acurate for all the projects and are only
  70 indicative. Contact the testing group for further details.
  71
  72
  73 Repository structure
  74 ---------------------
  75
  76 Most of the projects have a similar structure, which can be defined as follows::
  77
  78   `-- home
  79     |-- requirements.txt
  80     |-- setup.py
  81     |-- tox.ini
  82     |
  83     |-- <project>
  84     |       |-- <api>
  85     |       |-- <framework>
  86     |       `-- <test cases>
  87     |
  88     |-- docker
  89     |     |-- Dockerfile
  90     |     `-- Dockerfile.aarch64.patch
  91     |-- <unit tests>
  92     `- docs
  93        |-- release
  94        |   |-- release-notes
  95        |   `-- results
  96        `-- testing
  97            |-- developer
  98            |     `-- devguide
  99            |-- user
 100                  `-- userguide
 101
 102
 103 API
 104 ---
 105 Test projects are installing tools and triggering tests. When it is possible it
 106 is recommended to implement an API in order to perform the different actions.
 107
 108 Each test project should be able to expose and consume APIs from other test
 109 projects. This pseudo micro service approach should allow a flexible use of
 110 the different projects and reduce the risk of overlapping. In fact if project A
 111 provides an API to deploy a traffic generator, it is better to reuse it rather
 112 than implementing a new way to deploy it. This approach has not been implemented
 113 yet but the prerequisite consiting in exposing and API has already been done by
 114 several test projects.
 115
 116
 117 CLI
 118 ---
 119 Most of the test projects provide a docker as deliverable. Once connected, it is
 120 possible to prepare the environement and run tests through a CLI.
 121
 122
 123 Dockerization
 124 -------------
 125 Dockerization has been introduced in Brahmaputra and adopted by the test
 126 projects. Docker containers are pulled on the jumphost of OPNFV POD.
 127
 128
 129
 130
 131 Unit tests
 132 ----------
 133
 134
 135 Traffic generators
 136 ------------------
 137
 138
 139 ======================================
 140 Testing group configuration parameters
 141 ======================================
 142
 143
 144 Testing categories
 145 ==================
 146
 147 The testing group defined several categories also known as tiers. These
 148 categories can be used to group test suites.
 149
 150 +----------------+-------------------------------------------------------------+
 151 | Category       | Description                                                 |
 152 +================+=============================================================+
 153 | Healthcheck    | Simple and quick healthcheck tests case                     |
 154 +----------------+-------------------------------------------------------------+
 155 | Smoke          | Set of smoke test cases/suites to validate the release      |
 156 +----------------+-------------------------------------------------------------+
 157 | Features       | Test cases that validate a specific feature on top of OPNFV.|
 158 |                | Those come from Feature projects and need a bit of support  |
 159 |                | for integration                                             |
 160 +----------------+-------------------------------------------------------------+
 161 | Components     | Tests on a specific component (e.g. OpenStack, OVS, DPDK,..)|
 162 |                | It may extend smoke tests                                   |
 163 +----------------+-------------------------------------------------------------+
 164 | Performance    | Performance qualification                                   |
 165 +----------------+-------------------------------------------------------------+
 166 | VNF            | Test cases related to deploy an open source VNF including   |
 167 |                | an orchestrator                                             |
 168 +----------------+-------------------------------------------------------------+
 169 | Stress         | Stress and robustness tests                                 |
 170 +----------------+-------------------------------------------------------------+
 171 | In Service     | In service testing                                          |
 172 +----------------+-------------------------------------------------------------+
 173
 174 Testing domains
 175 ===============
 176
 177 The domains deal with the technical scope of the tests. It shall correspond to
 178 domains defined for the certification program:
 179
 180  * compute
 181  * network
 182  * storage
 183  * hypervisor
 184  * container
 185  * vim
 186  * mano
 187  * vnf
 188  * ...
 189
 190 Testing coverage
 191 =================
 192 One of the goals of the testing working group is to identify the poorly covered
 193 areas and avoid testing overlap.
 194 Ideally based on the declaration of the test cases, through the tags, domains
 195 and tier fields, it shall be possible to create heuristic maps.
 196
 197
 198 =================
 199 TestAPI framework
 200 =================
 201
 202 The OPNFV testing group created a test collection database to collect
 203 the test results from CI:
 204
 205
 206  http://testresults.opnfv.org/test/swagger/spec.html
 207
 208 Any test project running on any lab integrated in CI can push the
 209 results to this database.
 210 This database can be used to see the evolution of the tests and compare
 211 the results versus the installers, the scenarios or the labs.
 212 It is used to produce a dashboard with the current test status of the project.
 213
 214
 215 Overall Architecture
 216 ====================
 217 The Test result management can be summarized as follows::
 218
 219   +-------------+    +-------------+    +-------------+
 220   |             |    |             |    |             |
 221   |   Test      |    |   Test      |    |   Test      |
 222   | Project #1  |    | Project #2  |    | Project #N  |
 223   |             |    |             |    |             |
 224   +-------------+    +-------------+    +-------------+
 225            |               |               |
 226            V               V               V
 227        +-----------------------------------------+
 228        |                                         |
 229        |         Test Rest API front end         |
 230        |                                         |
 231        +-----------------------------------------+
 232            |                |
 233            |                V
 234            |     +-------------------------+
 235            |     |                         |
 236            |     |    Test Results DB      |
 237            |     |         Mongo DB        |
 238            |     |                         |
 239            |     +-------------------------+
 240            |
 241            |
 242      +----------------------+
 243      |                      |
 244      |    test Dashboard    |
 245      |                      |
 246      +----------------------+
 247
 248 TestAPI description
 249 ===================
 250 The TestAPI is used to declare pods, projects, test cases and test
 251 results. Pods are the sets of bare metal or virtual servers and networking
 252 equipments used to run the tests.
 253
 254 The results pushed in the database are related to pods, projects and test cases.
 255 If you try to push results of test done on non referenced pod, the API will
 256 return an error message.
 257
 258 An additional method dashboard has been added to post-process
 259 the raw results in release Brahmaputra (deprecated in Colorado).
 260
 261 The data model is very basic, 5 objects are created:
 262
 263   * Pods
 264   * Projects
 265   * Testcases
 266   * Results
 267   * Scenarios
 268
 269 The code of the API is hosted in the releng repository `[6]`_.
 270 The static documentation of the API can be found at `[7]`_.
 271 The TestAPI has been dockerized and may be installed locally in your
 272 lab. See `[15]`_ for details.
 273
 274 The deployment of the TestAPI has been automated.
 275 A jenkins job manages:
 276
 277   * the unit tests of the TestAPI
 278   * the creation of a new docker file
 279   * the deployment of the new TestAPI
 280   * the archive of the old TestAPI
 281   * the backup of the Mongo DB
 282
 283 TestAPI Authorization
 284 ---------------------
 285
 286 PUT/DELETE/POST operations of the TestAPI now require token based authorization. The token needs
 287 to be added in the request using a header 'X-Auth-Token' for access to the database.
 288
 289 e.g::
 290     headers['X-Auth-Token']
 291
 292 The value of the header i.e the token can be accessed in the jenkins environment variable
 293 *TestApiToken*. The token value is added as a masked password.
 294
 295 .. code-block:: python
 296
 297     headers['X-Auth-Token'] = os.environ.get('TestApiToken')
 298
 299 The above example is in Python. Token based authentication has been added so that only ci pods
 300 jenkins job can have access to the database.
 301
 302 Please note that currently token authorization is implemented but is not yet enabled.
 303
 304 ===============================
 305 Feedback from the testing group
 306 ================================
 307
 308 Test case catalog
 309 ===================
 310
 311 A test case catalog has been realized. Roll over the project then click to get
 312 the list of test cases, click on the case to get more details.
 313
 314 .. raw:: html
 315    :url: http://testresults.opnfv.org/reporting2/reporting/index.html#!/select/visual
 316
 317 Reporting
 318 =========
 319
 320 An automatic reporting page has been created in order to provide a
 321 consistent view of the scenarios.
 322
 323 In this page, each scenario is evaluated according to test criteria.
 324 The code for the automatic reporting is available at `[8]`_.
 325
 326 The results are collected from the centralized database every day and,
 327 per scenario. A score is calculated based on the results from the last
 328 10 days.
 329
 330 Dashboard
 331 =========
 332
 333 Dashboard is used to provide a consistent view of the results collected in CI.
 334 The results showed on the dashboard are post processed from the Database,
 335 which only contains raw results.
 336
 337 It can be used in addition of the reporting page (high level view) to allow
 338 the creation of specific graphs according to what the test owner wants to show.
 339
 340 In Brahmaputra, a basic home made dashboard was created in Functest.
 341 In Colorado, Yardstick adopted Grafana (time based graphs) and ELK (complex
 342 graphs).
 343 Since Danube, the testing community decided to adopt ELK framework and to rely
 344 on bitergia. It was not implemented for Danube but it is planned for Euphrates.
 345
 346 Bitergia already provides a dashboard for code and infrastructure.
 347 A new Test tab will be added. The dataset will be built by consuming
 348 the TestAPI.
 349
 350 See `[3]`_ for details.
 351
 352
 353 =======
 354 How TOs
 355 =======
 356
 357 Where can I find information on the different test projects?
 358 ===========================================================
 359
 360
 361 How can I contribute to a test project?
 362 =======================================
 363
 364
 365 Where can I find hardware resources?
 366 ====================================
 367
 368
 369 How do I integrate my tests in CI?
 370 ==================================
 371
 372
 373 How to declare my tests in the test Database?
 374 =============================================
 375
 376
 377 How to push your results into the Test Database?
 378 ================================================
 379
 380 The test database is used to collect test results. By default it is
 381 enabled only for CI tests from Production CI pods.
 382
 383 Please note that it is possible to create your own local database.
 384
 385 A dedicated database is for instance created for each plugfest.
 386
 387 The architecture and associated API is described in previous chapter.
 388 If you want to push your results from CI, you just have to call the API
 389 at the end of your script.
 390
 391 You can also reuse a python function defined in functest_utils.py `[5]`_
 392
 393
 394 Where can I find the documentation on the test API?
 395 ===================================================
 396
 397 http://artifacts.opnfv.org/releng/docs/testapi.html
 398
 399
 400
 401 I have tests, to which category should I declare them?
 402 ======================================================
 403
 404
 405
 406 The main ambiguity could be between features and VNF.
 407 In fact sometimes you have to spawn VMs to demonstrate the capabilities of the
 408 feature you introduced.
 409 We recommend to declare your test in the feature category.
 410
 411 VNF category is really dedicated to test including:
 412
 413  * creation of resources
 414  * deployement of an orchestrator/VNFM
 415  * deployment of the VNF
 416  * test of the VNFM
 417  * free resources
 418
 419 The goal is not to study a particular feature on the infrastructure but to have
 420 a whole end to end test of a VNF automatically deployed in CI.
 421 Moreover VNF are run in weekly jobs (one a week), feature tests are in daily
 422 jobs and use to get a scenario score.
 423
 424 Where are the logs of CI runs?
 425 ==============================
 426
 427 Logs and configuration files can be pushed to artifact server from the CI under
 428 http://artifacts.opnfv.org/<project name>
 429
 430
 431 ==========
 432 References
 433 ==========
 434
 435 _`[1]`: http://docs.opnfv.org/en/stable-danube/testing/ecosystem/overview.html
 436
 437 _`[2]`: http://www.opnfv.org
 438
 439 _`[3]`: https://wiki.opnfv.org/display/testing/Result+alignment+for+ELK+post-processing
 440
 441 _`[4]`: https://wiki.opnfv.org/display/INF/CI+Scenario+Naming
 442
 443 _`[5]`: https://git.opnfv.org/functest/tree/functest/utils/functest_utils.py#176
 444
 445 _`[6]`: https://git.opnfv.org/functest/tree/releng
 446
 447 _`[7]`: http://artifacts.opnfv.org/releng/docs/testapi.html
 448
 449 _`[8]`: https://wiki.opnfv.org/display/meetings/Test+Working+Group+Weekly+Meeting
 450
 451
 452 IRC support chan: #opnfv-testperf