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 OPNFV FUNCTEST developer guide
   6 ******************************
   7
   8 .. toctree::
   9    :numbered:
  10    :maxdepth: 2
  11
  12 Version history
  13 ===============
  14 +------------+----------+------------------+----------------------------------+
  15 | **Date**   | **Ver.** | **Author**       | **Comment**                      |
  16 |            |          |                  |                                  |
  17 +------------+----------+------------------+----------------------------------+
  18 | 2017-01-23 | 1.0.0    | Morgan Richomme  | Creation for Danube              |
  19 +------------+----------+------------------+----------------------------------+
  20 | 2017-08-16 | 1.0.1    | Morgan Richomme  | Adaptations for Euphrates        |
  21 |            |          |                  | - move generic part to Testing   |
  22 |            |          |                  | developer guide                  |
  23 |            |          |                  | - move reporting part to functest|
  24 |            |          |                  | user guide                       |
  25 |            |          |                  | - update test case list          |
  26 |            |          |                  | - include auto generated core    |
  27 |            |          |                  | documentation                    |
  28 +------------+----------+------------------+----------------------------------+
  29
  30 ============
  31 Introduction
  32 ============
  33
  34 Functest is a project dealing with functional testing.
  35 Functest produces its own internal test cases but can also be considered
  36 as a framework to support feature and VNF onboarding project testing.
  37
  38 Therefore there are many ways to contribute to Functest. You can:
  39
  40  * Develop new internal test cases
  41  * Integrate the tests from your feature project
  42  * Develop the framework to ease the integration of external test cases
  43
  44 Additional tasks involving Functest but addressing all the test projects
  45 may also be mentioned:
  46
  47   * Develop the API / Test collection framework
  48   * Develop dashboards or automatic reporting portals
  49
  50 This document describes how, as a developer, you may interact with the
  51 Functest project. The first section details the main working areas of
  52 the project. The Second part is a list of "How to" to help you to join
  53 the Functest family whatever your field of interest is.
  54
  55
  56 ========================
  57 Functest developer areas
  58 ========================
  59
  60
  61 Functest High level architecture
  62 ================================
  63
  64 Functest is a project delivering test containers dedicated to OPNFV.
  65 It includes the tools, the scripts and the test scenarios.
  66 Until Danube, Functest produced 2 docker files based on Ubuntu 14.04:
  67
  68   * x86 Functest: https://hub.docker.com/r/opnfv/functest/
  69   * aarch64 Functest: https://hub.docker.com/r/opnfv/functest_aarch64/
  70
  71 In Euphrates Alpine containers have been introduced in order to lighten the
  72 container and manage testing slicing, the new containers are created according
  73 to the different tiers:
  74
  75   * functest-core: https://hub.docker.com/r/opnfv/functest-core/
  76   * functest-healthcheck: https://hub.docker.com/r/opnfv/functest-healthcheck/
  77   * functest-smoke: https://hub.docker.com/r/opnfv/functest-smoke/
  78   * functest-features: TODO
  79   * functest-components: TODO
  80   * functest-vnf: TODO
  81
  82 Functest can be described as follow::
  83
  84  +----------------------+
  85  |                      |
  86  |   +--------------+   |                  +-------------------+
  87  |   |              |   |    Public        |                   |
  88  |   | Tools        |   +------------------+      OPNFV        |
  89  |   | Scripts      |   |                  | System Under Test |
  90  |   | Scenarios    |   +------------------+                   |
  91  |   |              |   |    Management    |                   |
  92  |   +--------------+   |                  +-------------------+
  93  |                      |
  94  |    Functest Docker   |
  95  |                      |
  96  +----------------------+
  97
  98 Functest internal test cases
  99 ============================
 100 The internal test cases in Euphrates are:
 101
 102
 103  * api_check
 104  * cloudify_ims
 105  * connection_check
 106  * vping_ssh
 107  * vping_userdata
 108  * odl
 109  * odl-netvirt
 110  * odl-fds
 111  * rally_full
 112  * rally_sanity
 113  * snaps_health_check
 114  * tempest_full_parallel
 115  * tempest_smoke_serial
 116  * cloudify_ims
 117
 118 By internal, we mean that this particular test cases have been developed and/or
 119 integrated by functest contributors and the associated code is hosted in the
 120 Functest repository.
 121 An internal case can be fully developed or a simple integration of
 122 upstream suites (e.g. Tempest/Rally developed in OpenStack, or odl suites are
 123 just integrated in Functest).
 124
 125 The structure of this repository is detailed in `[1]`_.
 126 The main internal test cases are in the opnfv_tests subfolder of the
 127 repository, the internal test cases are:
 128
 129  * sdn: odl, odl_netvirt, odl_fds, onos
 130  * openstack: api_check, connection_check, snaps_health_check, vping_ssh, vping_userdata, tempest_*, rally_*
 131  * vnf: cloudify_ims
 132
 133 If you want to create a new test case you will have to create a new folder under
 134 the testcases directory (See next section for details).
 135
 136 Functest external test cases
 137 ============================
 138 The external test cases are inherited from other OPNFV projects, especially the
 139 feature projects.
 140
 141 The external test cases are:
 142
 143  * barometer
 144  * bgpvpn
 145  * doctor
 146  * domino
 147  * onos
 148  * fds
 149  * orchestra_ims
 150  * parser
 151  * promise
 152  * refstack_defcore
 153  * snaps_smoke
 154  * functest-odl-sfc
 155  * vyos_vrouter
 156
 157 External test cases integrated in previous versions but not released in
 158 Euphrates:
 159
 160  * copper
 161  * netready
 162  * security_scan
 163
 164
 165 The code to run these test cases is hosted in the repository of the project.
 166
 167
 168 Functest framework
 169 ==================
 170
 171 Functest is a framework.
 172
 173 Historically Functest is released as a docker file, including tools, scripts and
 174 a CLI to prepare the environment and run tests.
 175 It simplifies the integration of external test suites in CI pipeline and provide
 176 commodity tools to collect and display results.
 177
 178 Since Colorado, test categories also known as tiers have been created to
 179 group similar tests, provide consistent sub-lists and at the end optimize
 180 test duration for CI (see How To section).
 181
 182 The definition of the tiers has been agreed by the testing working group.
 183
 184 The tiers are:
 185   * healthcheck
 186   * smoke
 187   * features
 188   * components
 189   * performance
 190   * vnf
 191   * stress
 192
 193 Note Functest deals with healthcheck, smoke, features, components and vnf tiers.
 194 Performance and stress tiers are out of scope.
 195
 196 Functest abstraction classes
 197 ============================
 198
 199 In order to harmonize test integration, abstraction classes have been
 200 introduced:
 201
 202  * testcase: base for any test case
 203  * unit: run unit tests as test case
 204  * feature: abstraction for feature project
 205  * vnf: abstraction for vnf onboarding
 206
 207 The goal is to unify the way to run tests in Functest.
 208
 209 Feature, unit and vnf_base inherit from testcase::
 210
 211               +-----------------------------------------+
 212               |                                         |
 213               |         TestCase                        |
 214               |                                         |
 215               |         - init()                        |
 216               |         - run()                         |
 217               |         - publish_report()              |
 218               |         - check_criteria()              |
 219               |                                         |
 220               +-----------------------------------------+
 221                  |               |
 222                  V               V
 223   +--------------------+   +--------------+   +--------------------------+
 224   |                    |   |              |   |                          |
 225   |    feature         |   |    unit      |   |      vnf                 |
 226   |                    |   |              |   |                          |
 227   |                    |   |              |   |  - prepare()             |
 228   |  - execute()       |   |              |   |  - deploy_orchestrator() |
 229   | BashFeature class  |   |              |   |  - deploy_vnf()          |
 230   |                    |   |              |   |  - test_vnf()            |
 231   |                    |   |              |   |  - clean()               |
 232   +--------------------+   +--------------+   +--------------------------+
 233
 234
 235 Testcase
 236 ========
 237 .. raw:: html
 238    :url: http://artifacts.opnfv.org/functest/docs/apidoc/functest.core.testcase.html
 239
 240 Feature
 241 =======
 242 .. raw:: html
 243    :url: http://artifacts.opnfv.org/functest/docs/apidoc/functest.core.feature.html
 244
 245 Unit
 246 ====
 247 .. raw:: html
 248    :url: http://artifacts.opnfv.org/functest/docs/apidoc/functest.core.unit.html
 249
 250 VNF
 251 ===
 252 .. raw:: html
 253    :url: http://artifacts.opnfv.org/functest/docs/apidoc/functest.core.vnf.html
 254
 255
 256 see `Functest framework overview`_ to get code samples
 257
 258
 259 Functest util classes
 260 =====================
 261
 262 In order to simplify the creation of test cases, Functest develops also some
 263 functions that can be used by any feature or internal test cases.
 264 Several features are supported such as logger, configuration management and
 265 Openstack capabilities (snapshot, clean, tacker,..).
 266 These functions can be found under <repo>/functest/utils and can be described as
 267 follows::
 268
 269  functest/utils/
 270  |-- config.py
 271  |-- constants.py
 272  |-- decoratos.py
 273  |-- env.py
 274  |-- functest_utils.py
 275  |-- openstack_clean.py
 276  |-- openstack_snapshot.py
 277  |-- openstack_tacker.py
 278  `-- openstack_utils.py
 279
 280 Please note that it is possible to use snaps utils. SNAPS `[4]`_ is an OPNFV
 281 project providing OpenStack utils.
 282
 283
 284 TestAPI
 285 =======
 286 Functest is using the Test collection framework and the TestAPI developed by
 287 the OPNFV community. See `OPNFV Test collection framework`_ for details.
 288
 289
 290 Reporting
 291 =========
 292 A web page is automatically generated every day to display the status based on
 293 jinja2 templates `[3]`_.
 294
 295
 296 Dashboard
 297 =========
 298
 299 Additional dashboarding is managed at the testing group level, see
 300 `OPNFV Testing dashboard`_
 301
 302
 303 =======
 304 How TOs
 305 =======
 306
 307 See `How to section`_ on Functest wiki
 308
 309
 310 ==========
 311 References
 312 ==========
 313
 314 _`[1]`: http://artifacts.opnfv.org/functest/docs/configguide/index.html Functest configuration guide
 315
 316 _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html functest user guide
 317
 318 _`[3]`: https://git.opnfv.org/cgit/releng/tree/utils/test/reporting
 319
 320 _`[4]`: https://git.opnfv.org/snaps/
 321
 322 _`Functest framework overview` : http://testresults.opnfv.org/functest/framework/index.html
 323
 324 _`OPNFV Test collection framework`: TODO
 325
 326 _`OPNFV Testing dashboard`: https://opnfv.biterg.io/goto/283dba93ca18e95964f852c63af1d1ba
 327
 328 _`How to section`: https://wiki.opnfv.org/pages/viewpage.action?pageId=7768932
 329
 330 IRC support chan: #opnfv-functest