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