diff options
Diffstat (limited to 'docs/devguide/index.rst')
| -rw-r--r-- | docs/devguide/index.rst | 280 |
1 files changed, 280 insertions, 0 deletions
diff --git a/docs/devguide/index.rst b/docs/devguide/index.rst new file mode 100644 index 000000000..e6a294f8a --- /dev/null +++ b/docs/devguide/index.rst @@ -0,0 +1,280 @@ +****************************** +OPNFV FUNCTEST developer guide +****************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + +============ +Introduction +============ + +This document describes how feature projects aiming to run functional tests can be integrated into FuncTest framework. + + +================================ +Functest High level architecture +================================ + +Functest is project delivering a test container dedicated to OPNFV. +It includes the tools, the scripts and the test scenarios. + +Functest can be described as follow:: + + +----------------------+ + | | + | +--------------+ | +-------------------+ + | | | | Public | | + | | Tools | +------------------+ OPNFV | + | | Scripts | | | System Under Test | + | | Scenarios | +------------------+ | + | | | | Management | | + | +--------------+ | +-------------------+ + | | + | Functest Docker | + | | + +----------------------+ + +Functest deals with internal and external test cases. +The Internal test cases in Brahmaputra are: + * vPing + * ODL + * Tempest + * vIMS + * Rally + +see `[2]`_ for details. + +Functest can also be considered as a framework that may include external OPNFV projects. +This framework will ease the integration of the feature test suite to the CI. + +================== +How Functest works +================== + +The installation and the launch of the Functest docker image is described in `[1]`_. + +The Functest docker directories are:: + + home + | + `-- opnfv + |-- functest + | |-- conf + | |-- data + | `-- results + `-- repos + |-- bgpvpn + |-- doctor + |-- functest + |-- odl_integration + |-- onos + |-- ovno + |-- promise + |-- rally + |-- releng + `-- vims-test + + ++--------------+-------------------+---------------------------------------------------------+ +| Directory | Subdirectory | Comments | ++--------------+-------------------+---------------------------------------------------------+ +| | <project>/conf | All the useful configuration file(s) for <project> | +| | | the openstack creds are put there for CI | +| | | It is recommended to push it there when passing the | +| | | credentials to container through the -v option | +| +-------------------+---------------------------------------------------------+ +| opnfv | <project>/data | Usefull data, images for <projects> | +| | | By default we put an image cirros-0.3.4-x86_64-disk.img | +| | | This image can be used by any projects | +| +-------------------+---------------------------------------------------------+ +| | <project>/results | Local result directory of project <project> | ++--------------+-------------------+---------------------------------------------------------+ +| | bgpvpn | | +| +-------------------+ + +| repos | doctor | | +| +-------------------+ + +| | functest | | +| +-------------------+ + +| | odl_integration | | +| +-------------------+ Clone of the useful repositories + +| | onos | These repositories may include: | +| +-------------------+ - tooling + +| | promise | - scenario | +| +-------------------+ - scripts + +| | rally | | +| +-------------------+ + +| | releng | | +| +-------------------+ + +| | vims-test | | +| +-------------------+ + +| | <your project> | | ++--------------+-------------------+---------------------------------------------------------+ + +Before running the test suite, you must prepare the environement by running:: + + $ /home/opnfv/repos/functest/docker/prepare_env.sh + +By running prepare_env.sh, you build the test environement required by the tests including the retrieval and sourcing of OpenStack credentials. +This is an example of the env variables we have in the docker container: + + * HOSTNAME=373f77816eb0 + * INSTALLER_TYPE=fuel + * repos_dir=/home/opnfv/repos + * INSTALLER_IP=10.20.0.2 + * PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + * PWD=/home/opnfv + * SHLVL=1 + * HOME=/home/opnfv + * NODE_NAME=opnfv-jump-2 + * creds=/home/opnfv/functest/conf/openstack.creds + * _=/usr/bin/env + +The prepare_env.sh will source the credentials, so once run you should have access to the following env variables:: + + root@373f77816eb0:~# env|grep OS_ + OS_REGION_NAME=RegionOne + OS_PROJECT_NAME=admin + OS_PASSWORD=admin + OS_AUTH_STRATEGY=keystone + OS_AUTH_URL=http://172.30.10.70:5000/v2.0 + OS_USERNAME=admin + OS_TENANT_NAME=admin + OS_ENDPOINT_TYPE=internalURL + OS_NO_CACHE=true + + +Then you may run the test suite by running:: + + $ /home/opnfv/repos/functest/docker/run_tests.sh -t <your project> + +see `[2]`_ for details. + + + +========================= +How to integrate Functest +========================= + +The files of the Functest repository you must modify to integrate Functest are: + + * functest/docker/Dockerfile + * functest/docker/common.sh + * functest/docker/requirements.pip + * functest/docker/run_tests.sh + * functest/docker/prepare_env.sh + * functest/config_funtest.yaml + + +Dockerfile +========== + +This file lists the repositories to be cloned in the Functest container. The repositories can be internal or external:: + + RUN git clone https://gerrit.opnfv.org/gerrit/<your porject> ${repos_dir}/<your project> + + +Common.sh +========== + +This file can be used to declare the branch and commit variables of your projects:: + + <YOUR_PROJECT>_BRANCH=$(cat $config_file | grep -w <your project>_branch | awk 'END {print $NF}') + <YOUR_PROJECT>_COMMIT=$(cat $config_file | grep -w <your project>_commit | awk 'END {print $NF}') + + echo "<YOUR_PROJECT>_BRANCH=${<YOUR_PROJECT>_BRANCH}" + echo "<YOUR_PROJECT>_COMMIT=${<YOUR_PROJECT>_COMMIT}" + + +requirements.pip +================ + +This file can be used to preloaded all the needed Python libraries (and avoid that each project does it) +The current libraries used in Functest container are:: + + # cat requirements.pip + pyyaml==3.10 + gitpython==1.0.1 + python-neutronclient==2.6.0 + python-novaclient==2.28.1 + python-glanceclient==1.1.0 + python-cinderclient==1.4.0 + python-ceilometerclient==1.5.1 + python-keystoneclient==1.6.0 + virtualenv==1.11.4 + pexpect==4.0 + requests==2.8.0 + robotframework==2.9.1 + robotframework-requests==0.3.8 + robotframework-sshlibrary==2.1.1 + configObj==5.0.6 + Flask==0.10.1 + + +prepare_env.sh +============ + +This script can be adapted if you need to set up a specific environment before running the tests. + +run_tests.sh +============ + +This script is used to run the tests. You must thus complete the cases with you own project:: + + ;; + "promise") + info "Running PROMISE test case..." + # TODO + ;; + "doctor") + info "Running Doctor test..." + python ${FUNCTEST_REPO_DIR}/testcases/features/doctor.py + ;; + "<your project>") + info "Running <your project> test..." + # your script that launchs your tests... + ;; + +And do not forget to update also the help line:: + + -t|--test run specific set of tests + <test_name> one or more of the following: vping,odl,rally,tempest,vims,onos, promise. Separated by comma. + + +config_funtest.yaml +=================== + +This file is the main configuration file of Functest. You must add the references to your project:: + + general: + directories: + dir_repo_<your project>: /home/opnfv/repos/<your project> + repositories: + # branch and commit ID to which the repos will be reset (HEAD) + <your project>_branch: master + <your project>_commit: latest + + +========== +References +========== + +.. _`[1]`: Functest configuration guide URL +.. _`[2]`: functest user guide URL + + +OPNFV main site: opnfvmain_. + +OPNFV functional test page: opnfvfunctest_. + +IRC support chan: #opnfv-testperf + +.. _opnfvmain: http://www.opnfv.org +.. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing +.. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html +.. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html +.. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py +.. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml + |