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