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