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    :maxdepth: 2
   9
  10 ============
  11 Introduction
  12 ============
  13
  14 Functest is a project dealing with functional testing.
  15 The project produces its own internal test cases but can also be considered
  16 as a framework to support feature and VNF onboarding project testing.
  17
  18 Therefore there are many ways to contribute to Functest. You can:
  19
  20  * Develop new internal test cases
  21  * Integrate the tests from your feature project
  22  * Develop the framework to ease the integration of external test cases
  23
  24 Additional tasks involving Functest but addressing all the test projects
  25 may also be mentioned:
  26
  27   * The API / Test collection framework
  28   * The dashboards
  29   * The automatic reporting portals
  30   * The testcase catalog
  31
  32 This document describes how, as a developer, you may interact with the
  33 Functest project. The first section details the main working areas of
  34 the project. The Second part is a list of "How to" to help you to join
  35 the Functest family whatever your field of interest is.
  36
  37
  38 ========================
  39 Functest developer areas
  40 ========================
  41
  42
  43 Functest High level architecture
  44 ================================
  45
  46 Functest is a project delivering test containers dedicated to OPNFV.
  47 It includes the tools, the scripts and the test scenarios.
  48 In Euphrates Alpine containers have been introduced in order to lighten the
  49 container and manage testing slicing. The new containers are created according
  50 to the different tiers:
  51
  52   * functest-core: https://hub.docker.com/r/opnfv/functest-core/
  53   * functest-healthcheck: https://hub.docker.com/r/opnfv/functest-healthcheck/
  54   * functest-smoke: https://hub.docker.com/r/opnfv/functest-smoke/
  55   * functest-vnf: https://hub.docker.com/r/opnfv/functest-vnf/
  56   * functest-restapi: https://hub.docker.com/r/opnfv/functest-restapi/
  57
  58 Standalone functest dockers are maintained for Euphrates but Alpine containers
  59 are recommended.
  60
  61 Functest can be described as follow::
  62
  63   +----------------------+
  64   |                      |
  65   |   +--------------+   |                  +-------------------+
  66   |   |              |   |    Public        |                   |
  67   |   | Tools        |   +------------------+      OPNFV        |
  68   |   | Scripts      |   |                  | System Under Test |
  69   |   | Scenarios    |   |                  |                   |
  70   |   |              |   |                  |                   |
  71   |   +--------------+   |                  +-------------------+
  72   |                      |
  73   |    Functest Docker   |
  74   |                      |
  75   +----------------------+
  76
  77 Functest internal test cases
  78 ============================
  79 The internal test cases in Euphrates are:
  80
  81
  82  * connection_check
  83  * vping_ssh
  84  * vping_userdata
  85  * odl
  86  * rally_full
  87  * rally_sanity
  88  * tempest_smoke
  89  * tempest_full
  90  * cloudify_ims
  91
  92 By internal, we mean that this particular test cases have been developed and/or
  93 integrated by functest contributors and the associated code is hosted in the
  94 Functest repository.
  95 An internal case can be fully developed or a simple integration of
  96 upstream suites (e.g. Tempest/Rally developed in OpenStack, or odl suites are
  97 just integrated in Functest).
  98
  99 The structure of this repository is detailed in `[1]`_.
 100 The main internal test cases are in the opnfv_tests subfolder of the
 101 repository, the internal test cases can be grouped by domain:
 102
 103  * sdn: odl, odl_fds
 104  * openstack: connection_check, vping_ssh, vping_userdata, tempest_*, rally_*
 105  * vnf: cloudify_ims
 106
 107 If you want to create a new test case you will have to create a new folder
 108 under the testcases directory (See next section for details).
 109
 110 Functest framework
 111 ==================
 112
 113 Functest is a framework.
 114
 115 Historically Functest is released as a docker file, including tools, scripts
 116 and a CLI to prepare the environment and run tests.
 117 It simplifies the integration of external test suites in CI pipeline and
 118 provide commodity tools to collect and display results.
 119
 120 Since Colorado, test categories also known as **tiers** have been created to
 121 group similar tests, provide consistent sub-lists and at the end optimize
 122 test duration for CI (see How To section).
 123
 124 The definition of the tiers has been agreed by the testing working group.
 125
 126 The tiers are:
 127   * healthcheck
 128   * smoke
 129   * benchmarking
 130   * features
 131   * vnf
 132
 133 Functest abstraction classes
 134 ============================
 135
 136 In order to harmonize test integration, abstraction classes have been
 137 introduced:
 138
 139  * testcase: base for any test case
 140  * unit: run unit tests as test case
 141  * feature: abstraction for feature project
 142  * vnf: abstraction for vnf onboarding
 143
 144 The goal is to unify the way to run tests in Functest.
 145
 146 Feature, unit and vnf_base inherit from testcase::
 147
 148               +----------------------------------------------------------------+
 149               |                                                                |
 150               |                   TestCase                                     |
 151               |                                                                |
 152               |                   - init()                                     |
 153               |                   - run()                                      |
 154               |                   - push_to_db()                               |
 155               |                   - is_successful()                            |
 156               |                                                                |
 157               +----------------------------------------------------------------+
 158                  |             |                 |                           |
 159                  V             V                 V                           V
 160   +--------------------+   +---------+   +------------------------+   +-----------------+
 161   |                    |   |         |   |                        |   |                 |
 162   |    feature         |   |  unit   |   |    vnf                 |   | robotframework  |
 163   |                    |   |         |   |                        |   |                 |
 164   |                    |   |         |   |- prepare()             |   |                 |
 165   |  - execute()       |   |         |   |- deploy_orchestrator() |   |                 |
 166   | BashFeature class  |   |         |   |- deploy_vnf()          |   |                 |
 167   |                    |   |         |   |- test_vnf()            |   |                 |
 168   |                    |   |         |   |- clean()               |   |                 |
 169   +--------------------+   +---------+   +------------------------+   +-----------------+
 170
 171
 172 Functest util classes
 173 =====================
 174
 175 In order to simplify the creation of test cases, Functest develops also some
 176 functions that are used by internal test cases.
 177 Several features are supported such as logger, configuration management and
 178 Openstack capabilities (tacker,..).
 179 These functions can be found under <repo>/functest/utils and can be described
 180 as follows::
 181
 182  functest/utils/
 183  |-- config.py
 184  |-- constants.py
 185  |-- decorators.py
 186  |-- env.py
 187  |-- functest_utils.py
 188  |-- openstack_tacker.py
 189  `-- openstack_utils.py
 190
 191
 192 TestAPI
 193 =======
 194 Functest is using the Test collection framework and the TestAPI developed by
 195 the OPNFV community. See `[4]`_ for details.
 196
 197
 198 Reporting
 199 =========
 200 A web page is automatically generated every day to display the status based on
 201 jinja2 templates `[3]`_.
 202
 203
 204 Dashboard
 205 =========
 206
 207 Additional dashboarding is managed at the testing group level, see `[5]`_ for
 208 details.
 209
 210
 211 =======
 212 How TOs
 213 =======
 214
 215 See How to section on Functest wiki `[6]`_
 216
 217
 218 ==========
 219 References
 220 ==========
 221
 222 _`[1]`: http://artifacts.opnfv.org/functest/docs/configguide/index.html Functest configuration guide
 223
 224 _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html functest user guide
 225
 226 _`[3]`: https://github.com/opnfv/releng-testresults/tree/master/reporting
 227
 228 _`[4]`: https://wiki.opnfv.org/display/functest/2017+Beijing?preview=%2F11699623%2F11700523%2FTestAPI+-+test+results+collection+service.pptx
 229
 230 _`[5]`: https://opnfv.biterg.io/login?nextUrl=%2Fgoto%2F283dba93ca18e95964f852c63af1d1ba
 231
 232 _`[6]`: https://wiki.opnfv.org/pages/viewpage.action?pageId=7768932
 233
 234 IRC support chan: #opnfv-functest