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