docs/testing/developer/devguide/index.rst

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