docs/testing/developer/devguide/index.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 Test 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 =================
  26 Developer journey
  27 =================
  28
  29 Be involved in the testing group
  30 ================================
  31
  32 Best practices
  33 ==============
  34
  35 Unit tests
  36 ----------
  37
  38 Dockerization
  39 -------------
  40
  41 API
  42 ---
  43
  44 CLI
  45 ---
  46
  47 Traffic generators
  48 ------------------
  49
  50 Towards a pseudo micro services approach
  51 ----------------------------------------
  52
  53 ======================================
  54 Testing group configuration parameters
  55 ======================================
  56
  57
  58 Testing categories
  59 ==================
  60
  61 The testing group defined several categories also known as tiers. These
  62 categories can be used to group test suites.
  63
  64 +----------------+-------------------------------------------------------------+
  65 | healthcheck    | Simple and quick healthcheck tests case                     |
  66 +----------------+-------------------------------------------------------------+
  67 | Smoke          | Set of smoke test cases/suites to validate the release      |
  68 +----------------+-------------------------------------------------------------+
  69 | Features       | Test cases that validate a specific feature on top of OPNFV.|
  70 |                | Those come from Feature projects and need a bit of support  |
  71 |                | for integration                                             |
  72 +----------------+-------------------------------------------------------------+
  73 | Components     | Tests on a specific component (e.g. OpenStack, OVS, DPDK,..)|
  74 |                | It may extend smoke tests                                   |
  75 +----------------+-------------------------------------------------------------+
  76 | Performance    | Performance qualification                                   |
  77 +----------------+-------------------------------------------------------------+
  78 | VNF            | Test cases related to deploy an open source VNF including   |
  79 |                | an orchestrator                                             |
  80 +----------------+-------------------------------------------------------------+
  81 | Stress         | Stress and robustness tests                                 |
  82 +----------------+-------------------------------------------------------------+
  83 | In Service     | In service testing                                          |
  84 +----------------+-------------------------------------------------------------+
  85
  86 Testing domains
  87 ===============
  88
  89 The domains deal with the technical scope of the tests. It shall correspond to
  90 domains defined for the certification program:
  91
  92  * compute
  93  * network
  94  * storage
  95  * hypervisor
  96  * container
  97  * vim
  98  * mano
  99  * vnf
 100  * ...
 101
 102 Testing coverage
 103 =================
 104 One of the goals of the testing working group is to identify the poorly covered
 105 areas and avoid testing overlap.
 106 Ideally based on the declaration of the test cases, through the tags, domains
 107 and tier fields, it shall be possible to create heuristic maps.
 108
 109
 110 ==============================
 111 Testing group generic enablers
 112 ==============================
 113
 114
 115 TestAPI framework
 116 =================
 117
 118 The OPNFV testing group created a test collection database to collect
 119 the test results from CI:
 120
 121
 122  http://testresults.opnfv.org/test/swagger/spec.html
 123
 124 Any test project running on any lab integrated in CI can push the
 125 results to this database.
 126 This database can be used to see the evolution of the tests and compare
 127 the results versus the installers, the scenarios or the labs.
 128 It is used to produce a dashboard with the current test status of the project.
 129
 130
 131 Overall Architecture
 132 --------------------
 133 The Test result management can be summarized as follows::
 134
 135   +-------------+    +-------------+    +-------------+
 136   |             |    |             |    |             |
 137   |   Test      |    |   Test      |    |   Test      |
 138   | Project #1  |    | Project #2  |    | Project #N  |
 139   |             |    |             |    |             |
 140   +-------------+    +-------------+    +-------------+
 141            |               |               |
 142            V               V               V
 143        +-----------------------------------------+
 144        |                                         |
 145        |         Test Rest API front end         |
 146        |                                         |
 147        +-----------------------------------------+
 148            A                |
 149            |                V
 150            |     +-------------------------+
 151            |     |                         |
 152            |     |    Test Results DB      |
 153            |     |         Mongo DB        |
 154            |     |                         |
 155            |     +-------------------------+
 156            |
 157            |
 158      +----------------------+
 159      |                      |
 160      |    test Dashboard    |
 161      |                      |
 162      +----------------------+
 163
 164 TestAPI description
 165 -------------------
 166 The TestAPI is used to declare pods, projects, test cases and test
 167 results. Pods are the sets of bare metal or virtual servers and networking
 168 equipments used to run the tests.
 169
 170 The results pushed in the database are related to pods, projects and test cases.
 171 If you try to push results of test done on non referenced pod, the API will
 172 return an error message.
 173
 174 An additional method dashboard has been added to post-process
 175 the raw results in release Brahmaputra (deprecated in Colorado).
 176
 177 The data model is very basic, 5 objects are created:
 178
 179   * Pods
 180   * Projects
 181   * Testcases
 182   * Results
 183   * Scenarios
 184
 185 The code of the API is hosted in the releng repository `[6]`_.
 186 The static documentation of the API can be found at `[7]`_.
 187 The TestAPI has been dockerized and may be installed locally in your
 188 lab. See `[15]`_ for details.
 189
 190 The deployment of the TestAPI has been automated.
 191 A jenkins job manages:
 192
 193   * the unit tests of the TestAPI
 194   * the creation of a new docker file
 195   * the deployment of the new TestAPI
 196   * the archive of the old TestAPI
 197   * the backup of the Mongo DB
 198
 199 TestAPI Authorization
 200 ~~~~~~~~~~~~~~~~~~~~~
 201
 202 PUT/DELETE/POST operations of the TestAPI now require token based authorization. The token needs
 203 to be added in the request using a header 'X-Auth-Token' for access to the database.
 204
 205 e.g::
 206     headers['X-Auth-Token']
 207
 208 The value of the header i.e the token can be accessed in the jenkins environment variable
 209 *TestApiToken*. The token value is added as a masked password.
 210
 211 .. code-block:: python
 212
 213     headers['X-Auth-Token'] = os.environ.get('TestApiToken')
 214
 215 The above example is in Python. Token based authentication has been added so that only ci pods
 216 jenkins job can have access to the database.
 217
 218 Please note that currently token authorization is implemented but is not yet enabled.
 219
 220 Reporting
 221 =========
 222
 223 An automatic reporting page has been created in order to provide a
 224 consistent view of the scenarios.
 225
 226 In this page, each scenario is evaluated according to test criteria.
 227 The code for the automatic reporting is available at `[8]`_.
 228
 229 The results are collected from the centralized database every day and,
 230 per scenario. A score is calculated based on the results from the last
 231 10 days.
 232
 233 Dashboard
 234 =========
 235
 236 Dashboard is used to provide a consistent view of the results collected in CI.
 237 The results showed on the dashboard are post processed from the Database,
 238 which only contains raw results.
 239
 240 It can be used in addition of the reporting page (high level view) to allow
 241 the creation of specific graphs according to what the test owner wants to show.
 242
 243 In Brahmaputra, a basic home made dashboard was created in Functest.
 244 In Colorado, Yardstick adopted Grafana (time based graphs) and ELK (complex
 245 graphs).
 246 Since Danube, the testing community decided to adopt ELK framework and to rely
 247 on bitergia. It was not implemented for Danube but it is planned for Euphrates.
 248
 249 Bitergia already provides a dashboard for code and infrastructure.
 250 A new Test tab will be added. The dataset will be built by consuming
 251 the TestAPI.
 252
 253 See `[3]`_ for details.
 254
 255
 256 =======
 257 How TOs
 258 =======
 259
 260 Where can I find information on the different test projects?
 261 ===========================================================
 262
 263
 264 How can I contribute to a test project?
 265 =======================================
 266
 267
 268 Where can I find hardware resources?
 269 ====================================
 270
 271
 272 How do I integrate my tests in CI?
 273 ==================================
 274
 275
 276 How to declare my tests in the test Database?
 277 =============================================
 278
 279
 280 How to push your results into the Test Database?
 281 ================================================
 282
 283 The test database is used to collect test results. By default it is
 284 enabled only for CI tests from Production CI pods.
 285
 286 Please note that it is possible to create your own local database.
 287
 288 A dedicated database is for instance created for each plugfest.
 289
 290 The architecture and associated API is described in previous chapter.
 291 If you want to push your results from CI, you just have to call the API
 292 at the end of your script.
 293
 294 You can also reuse a python function defined in functest_utils.py `[5]`_
 295
 296
 297 Where can I find the documentation on the test API?
 298 ===================================================
 299
 300 http://artifacts.opnfv.org/releng/docs/testapi.html
 301
 302
 303
 304 I have tests, to which category should I declare them?
 305 ======================================================
 306
 307
 308
 309 The main ambiguity could be between features and VNF.
 310 In fact sometimes you have to spawn VMs to demonstrate the capabilities of the
 311 feature you introduced.
 312 We recommend to declare your test in the feature category.
 313
 314 VNF category is really dedicated to test including:
 315
 316  * creation of resources
 317  * deployement of an orchestrator/VNFM
 318  * deployment of the VNF
 319  * test of the VNFM
 320  * free resources
 321
 322 The goal is not to study a particular feature on the infrastructure but to have
 323 a whole end to end test of a VNF automatically deployed in CI.
 324 Moreover VNF are run in weekly jobs (one a week), feature tests are in daily
 325 jobs and use to get a scenario score.
 326
 327 Where are the logs of CI runs?
 328 ==============================
 329
 330 Logs and configuration files can be pushed to artifact server from the CI under
 331 http://artifacts.opnfv.org/<project name>
 332
 333
 334 ==========
 335 References
 336 ==========
 337
 338 _`[1]`: http://docs.opnfv.org/en/stable-danube/testing/ecosystem/overview.html
 339
 340 _`[2]`: http://www.opnfv.org
 341
 342 _`[3]`: https://wiki.opnfv.org/display/testing/Result+alignment+for+ELK+post-processing
 343
 344 _`[4]`: https://wiki.opnfv.org/display/INF/CI+Scenario+Naming
 345
 346 _`[5]`: https://git.opnfv.org/functest/tree/functest/utils/functest_utils.py#176
 347
 348 _`[6]`: https://git.opnfv.org/functest/tree/releng
 349
 350 _`[7]`: http://artifacts.opnfv.org/releng/docs/testapi.html
 351
 352
 353 IRC support chan: #opnfv-testperf