docs/devguide/index.rst

   1 ******************************
   2 OPNFV FUNCTEST developer guide
   3 ******************************
   4
   5 .. toctree::
   6    :numbered:
   7    :maxdepth: 2
   8
   9
  10 ============
  11 Introduction
  12 ============
  13
  14 This document describes how feature projects aiming to run functional tests can be integrated into FuncTest framework.
  15
  16
  17 ================================
  18 Functest High level architecture
  19 ================================
  20
  21 Functest is project delivering a test container dedicated to OPNFV.
  22 It includes the tools, the scripts and the test scenarios.
  23
  24 Functest can be described as follow::
  25
  26  +----------------------+
  27  |                      |
  28  |   +--------------+   |                  +-------------------+
  29  |   |              |   |    Public        |                   |
  30  |   | Tools        |   +------------------+      OPNFV        |
  31  |   | Scripts      |   |                  | System Under Test |
  32  |   | Scenarios    |   +------------------+                   |
  33  |   |              |   |    Management    |                   |
  34  |   +--------------+   |                  +-------------------+
  35  |                      |
  36  |    Functest Docker   |
  37  |                      |
  38  +----------------------+
  39
  40 Functest deals with internal and external test cases.
  41 The Internal test cases in Brahmaputra are:
  42  * vPing
  43  * ODL
  44  * Tempest
  45  * vIMS
  46  * Rally
  47
  48 see `[2]`_ for details.
  49
  50 Functest can also be considered as a framework that may include external OPNFV projects.
  51 This framework will ease the integration of the feature test suite to the CI.
  52
  53 ==================
  54 How Functest works
  55 ==================
  56
  57 The installation and the launch of the Functest docker image is described in `[1]`_.
  58
  59 The Functest docker directories are::
  60
  61  home
  62     |
  63     `-- opnfv
  64         |-- functest
  65         |   |-- conf
  66         |   |-- data
  67         |   `-- results
  68         `-- repos
  69             |-- bgpvpn
  70             |-- doctor
  71             |-- functest
  72             |-- odl_integration
  73             |-- onos
  74             |-- ovno
  75             |-- promise
  76             |-- rally
  77             |-- releng
  78             `-- vims-test
  79
  80
  81 +--------------+-------------------+---------------------------------------------------------+
  82 | Directory    | Subdirectory      | Comments                                                |
  83 +--------------+-------------------+---------------------------------------------------------+
  84 |              | <project>/conf    | All the useful configuration file(s) for <project>      |
  85 |              |                   | the openstack creds are put there for CI                |
  86 |              |                   | It is recommended to push it there when passing the     |
  87 |              |                   | credentials to container through the -v option          |
  88 |              +-------------------+---------------------------------------------------------+
  89 |    opnfv     | <project>/data    | Usefull data, images for <projects>                     |
  90 |              |                   | By default we put an image cirros-0.3.4-x86_64-disk.img |
  91 |              |                   | This image can be used by any projects                  |
  92 |              +-------------------+---------------------------------------------------------+
  93 |              | <project>/results | Local result directory of project <project>             |
  94 +--------------+-------------------+---------------------------------------------------------+
  95 |              | bgpvpn            |                                                         |
  96 |              +-------------------+                                                         +
  97 | repos        | doctor            |                                                         |
  98 |              +-------------------+                                                         +
  99 |              | functest          |                                                         |
 100 |              +-------------------+                                                         +
 101 |              | odl_integration   |                                                         |
 102 |              +-------------------+    Clone of the useful repositories                     +
 103 |              | onos              |     These repositories may include:                     |
 104 |              +-------------------+                - tooling                                +
 105 |              | promise           |                - scenario                               |
 106 |              +-------------------+                - scripts                                +
 107 |              | rally             |                                                         |
 108 |              +-------------------+                                                         +
 109 |              | releng            |                                                         |
 110 |              +-------------------+                                                         +
 111 |              | vims-test         |                                                         |
 112 |              +-------------------+                                                         +
 113 |              | <your project>    |                                                         |
 114 +--------------+-------------------+---------------------------------------------------------+
 115
 116 Before running the test suite, you must prepare the environement by running::
 117
 118  $ /home/opnfv/repos/functest/docker/prepare_env.sh
 119
 120 By running prepare_env.sh, you build the test environement required by the tests including the retrieval and sourcing of OpenStack credentials.
 121 This is an example of the env variables we have in the docker container:
 122
 123  * HOSTNAME=373f77816eb0
 124  * INSTALLER_TYPE=fuel
 125  * repos_dir=/home/opnfv/repos
 126  * INSTALLER_IP=10.20.0.2
 127  * PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 128  * PWD=/home/opnfv
 129  * SHLVL=1
 130  * HOME=/home/opnfv
 131  * NODE_NAME=opnfv-jump-2
 132  * creds=/home/opnfv/functest/conf/openstack.creds
 133  * _=/usr/bin/env
 134
 135 The prepare_env.sh will source the credentials, so once run you should have access to the following env variables::
 136
 137  root@373f77816eb0:~# env|grep OS_
 138  OS_REGION_NAME=RegionOne
 139  OS_PROJECT_NAME=admin
 140  OS_PASSWORD=admin
 141  OS_AUTH_STRATEGY=keystone
 142  OS_AUTH_URL=http://172.30.10.70:5000/v2.0
 143  OS_USERNAME=admin
 144  OS_TENANT_NAME=admin
 145  OS_ENDPOINT_TYPE=internalURL
 146  OS_NO_CACHE=true
 147
 148
 149 Then you may run the test suite by running::
 150
 151  $ /home/opnfv/repos/functest/docker/run_tests.sh -t <your project>
 152
 153 see `[2]`_ for details.
 154
 155
 156
 157 =========================
 158 How to integrate Functest
 159 =========================
 160
 161 The files of the Functest repository you must modify to integrate Functest are:
 162
 163  * functest/docker/Dockerfile
 164  * functest/docker/common.sh
 165  * functest/docker/requirements.pip
 166  * functest/docker/run_tests.sh
 167  * functest/docker/prepare_env.sh
 168  * functest/config_funtest.yaml
 169
 170
 171 Dockerfile
 172 ==========
 173
 174 This file lists the repositories to be cloned in the Functest container. The repositories can be internal or external::
 175
 176  RUN git clone https://gerrit.opnfv.org/gerrit/<your porject> ${repos_dir}/<your project>
 177
 178
 179 Common.sh
 180 ==========
 181
 182 This file can be used to declare the branch and commit  variables of your projects::
 183
 184  <YOUR_PROJECT>_BRANCH=$(cat $config_file | grep -w <your project>_branch | awk 'END {print $NF}')
 185  <YOUR_PROJECT>_COMMIT=$(cat $config_file | grep -w <your project>_commit | awk 'END {print $NF}')
 186
 187  echo "<YOUR_PROJECT>_BRANCH=${<YOUR_PROJECT>_BRANCH}"
 188  echo "<YOUR_PROJECT>_COMMIT=${<YOUR_PROJECT>_COMMIT}"
 189
 190
 191 requirements.pip
 192 ================
 193
 194 This file can be used to preloaded all the needed Python libraries (and avoid that each project does it)
 195 The current libraries used in Functest container are::
 196
 197  # cat requirements.pip
 198  pyyaml==3.10
 199  gitpython==1.0.1
 200  python-neutronclient==2.6.0
 201  python-novaclient==2.28.1
 202  python-glanceclient==1.1.0
 203  python-cinderclient==1.4.0
 204  python-ceilometerclient==1.5.1
 205  python-keystoneclient==1.6.0
 206  virtualenv==1.11.4
 207  pexpect==4.0
 208  requests==2.8.0
 209  robotframework==2.9.1
 210  robotframework-requests==0.3.8
 211  robotframework-sshlibrary==2.1.1
 212  configObj==5.0.6
 213  Flask==0.10.1
 214
 215
 216 prepare_env.sh
 217 ============
 218
 219 This script can be adapted if you need to set up a specific environment before running the tests.
 220
 221 run_tests.sh
 222 ============
 223
 224 This script is used to run the tests. You must thus complete the cases with you own project::
 225
 226  ;;
 227     "promise")
 228         info "Running PROMISE test case..."
 229         # TODO
 230     ;;
 231     "doctor")
 232         info "Running Doctor test..."
 233         python ${FUNCTEST_REPO_DIR}/testcases/features/doctor.py
 234     ;;
 235     "<your project>")
 236         info "Running <your project> test..."
 237         # your script that launchs your tests...
 238     ;;
 239
 240 And do not forget to update also the help line::
 241
 242  -t|--test         run specific set of tests
 243       <test_name>     one or more of the following: vping,odl,rally,tempest,vims,onos, promise. Separated by comma.
 244
 245
 246 config_funtest.yaml
 247 ===================
 248
 249 This file is the main configuration file of Functest. You must add the references to your project::
 250
 251  general:
 252     directories:
 253         dir_repo_<your project>:      /home/opnfv/repos/<your project>
 254      repositories:
 255         # branch and commit ID to which the repos will be reset (HEAD)
 256         <your project>_branch:   master
 257         <your project>_commit:   latest
 258
 259
 260 ==========
 261 References
 262 ==========
 263
 264 .. _`[1]`: Functest configuration guide URL
 265 .. _`[2]`: functest user guide URL
 266
 267
 268 OPNFV main site: opnfvmain_.
 269
 270 OPNFV functional test page: opnfvfunctest_.
 271
 272 IRC support chan: #opnfv-testperf
 273
 274 .. _opnfvmain: http://www.opnfv.org
 275 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 276 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 277 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 278 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 279 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml
 280