From c288c8bc9e490ad968e190b2ef9db0415d80ba89 Mon Sep 17 00:00:00 2001 From: Morgan Richomme Date: Mon, 18 Jan 2016 18:44:36 +0100 Subject: Add developer guide JIRA: FUNCTEST-114 Change-Id: I359070c026a7456c73e2a5a27bf15c7ead4a1d35 Signed-off-by: Morgan Richomme --- docs/devguide/index.rst | 280 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 docs/devguide/index.rst 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 | ++--------------+-------------------+---------------------------------------------------------+ +| | /conf | All the useful configuration file(s) for | +| | | 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 | /data | Usefull data, images for | +| | | By default we put an image cirros-0.3.4-x86_64-disk.img | +| | | This image can be used by any projects | +| +-------------------+---------------------------------------------------------+ +| | /results | Local result directory of 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 | | +| +-------------------+ + +| | | | ++--------------+-------------------+---------------------------------------------------------+ + +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 + +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/ ${repos_dir}/ + + +Common.sh +========== + +This file can be used to declare the branch and commit variables of your projects:: + + _BRANCH=$(cat $config_file | grep -w _branch | awk 'END {print $NF}') + _COMMIT=$(cat $config_file | grep -w _commit | awk 'END {print $NF}') + + echo "_BRANCH=${_BRANCH}" + echo "_COMMIT=${_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 + ;; + "") + info "Running test..." + # your script that launchs your tests... + ;; + +And do not forget to update also the help line:: + + -t|--test run specific set of tests + 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_: /home/opnfv/repos/ + repositories: + # branch and commit ID to which the repos will be reset (HEAD) + _branch: master + _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 + -- cgit 1.2.3-korg