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