docs/testing/user/userguide/posca_guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) Huawei Technologies Co.,Ltd and others.
   4
   5 *********************
   6 POSCA Testsuite Guide
   7 *********************
   8
   9
  10 POSCA Introduction
  11 ====================
  12 The POSCA (Parametric Bottlenecks Testing Catalogue) test suite
  13 classifies the bottlenecks test cases and results into 5 categories.
  14 Then the results will be analyzed and bottlenecks will be searched
  15 among these categories.
  16
  17 The POSCA testsuite aims to locate the bottlenecks in parametric
  18 manner and to decouple the bottlenecks regarding the deployment
  19 requirements.
  20 The POSCA testsuite provides an user friendly way to profile and
  21 understand the E2E system behavior and deployment requirements.
  22
  23 Goals of the POSCA testsuite:
  24  a) Automatically locate the bottlenecks in a iterative manner.
  25  b) Automatically generate the testing report for bottlenecks in different categories.
  26  c) Implementing Automated Staging.
  27
  28 Scopes of the POSCA testsuite:
  29  a) Modeling, Testing and Test Result analysis.
  30  b) Parameters choosing and Algorithms.
  31
  32 Test stories of POSCA testsuite:
  33  a) Factor test (Stress test): base test cases that Feature test and Optimization will be dependant on or stress test to validate system.
  34  b) Feature test: test cases for features/scenarios.
  35  c) Optimization test: test to tune the system parameter.
  36
  37 Detailed workflow is illutrated below.
  38
  39 * https://wiki.opnfv.org/display/bottlenecks
  40
  41
  42 Preinstall Packages
  43 ====================
  44
  45 * Docker: https://docs.docker.com/engine/installation/
  46     * For Ubuntu, please refer to https://docs.docker.com/engine/installation/linux/ubuntu/
  47
  48 [Since Euphrates release, the docker-compose package is not required.]
  49
  50 * Docker-Compose: https://docs.docker.com/compose/
  51
  52 .. code-block:: bash
  53
  54     if [ -d usr/local/bin/docker-compose ]; then
  55         rm -rf usr/local/bin/docker-compose
  56     fi
  57     curl -L https://github.com/docker/compose/releases/download/1.11.0/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
  58     chmod +x /usr/local/bin/docker-compose
  59
  60
  61 Run POSCA Locally
  62 =================
  63
  64 The test environment preparation, the installation of the testing tools,
  65 the execution of the tests and the reporting/analyisis of POSCA test suite
  66 are highly automated.
  67 A few steps are needed to run it locally.
  68
  69 In Euphrates, Bottlenecks has modified its framework to support installer-agnostic
  70 testing which means that test cases could be executed over different deployments.
  71
  72
  73 Downloading Bottlenecks Software
  74 --------------------------------
  75
  76 .. code-block:: bash
  77
  78     mkdir /home/opnfv
  79     cd /home/opnfv
  80     git clone https://gerrit.opnfv.org/gerrit/bottlenecks
  81     cd bottlenecks
  82
  83
  84 Preparing Python Virtual Evnironment
  85 ------------------------------------
  86
  87 .. code-block:: bash
  88
  89     . pre_virt_env.sh
  90
  91
  92 Preparing configuration/description files
  93 -----------------------------------------
  94
  95 Put OpenStack RC file (admin_rc.sh), os_carcert and pod.yaml (pod descrition file) in /tmp directory.
  96 Edit admin_rc.sh and add the following line
  97
  98 .. code-block:: bash
  99
 100     export OS_CACERT=/tmp/os_cacert
 101
 102 If you have deployed your openstack environment by compass,
 103 you could use the following command to get the required files. For Fuel, Apex and JOID installer, we only provide limited support now
 104 for retrieving the configuration/description files. If you find that the following command can not do the magic, you should put the
 105 required files in /tmp manually.
 106
 107 .. code-block:: bash
 108
 109     bash /utils/env_prepare/config_prepare.sh -i <installer> [--debug]
 110
 111 Note that if we execute the command above, then admin_rc.sh and pod.yml gets created automatically in /tmp folder along with the line `export OS_CACERT=/tmp/os_cacert` added in admin_rc.sh file.
 112
 113
 114 Executing Specified Testcase
 115 ---------------------------
 116
 117 1. Bottlenecks provides a CLI interface to run the tests, which is one of the most convenient way since it is more close to our natural languge. An GUI interface with rest API will also be provided in later update.
 118
 119 .. code-block:: bash
 120
 121     bottlenecks testcase|teststory run <testname>
 122
 123 For the *testcase* command, testname should be as the same name of the test case configuration file located in testsuites/posca/testcase_cfg.
 124 For stress tests in Danube/Euphrates, *testcase* should be replaced by either *posca_factor_ping* or *posca_factor_system_bandwidth*.
 125 For the *teststory* command, a user can specify the test cases to be executed by defining it in a teststory configuration file located in testsuites/posca/testsuite_story. There is also an example there named *posca_factor_test*.
 126
 127 2. There are also other 2 ways to run test cases and test stories.
 128
 129     The first one is to use shell script.
 130
 131 .. code-block:: bash
 132
 133     bash run_tests.sh [-h|--help] -s <testsuite>|-c <testcase>
 134
 135
 136     The second is to use python interpreter.
 137
 138 .. code-block:: bash
 139
 140     $REPORT=False
 141     opts="--privileged=true -id"
 142     docker_volume="-v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp"
 143     docker run $opts --name bottlenecks-load-master $docker_volume opnfv/bottlenecks:latest /bin/bash
 144     sleep 5
 145     POSCA_SCRIPT="/home/opnfv/bottlenecks/testsuites/posca"
 146     docker exec bottlenecks-load-master python ${POSCA_SCRIPT}/../run_posca.py testcase|teststory <testname> ${REPORT}
 147
 148
 149 Showing Report
 150 --------------
 151
 152 Bottlenecks uses ELK to illustrate the testing results.
 153 Asumming IP of the SUT (System Under Test) is denoted as ipaddr,
 154 then the address of Kibana is http://[ipaddr]:5601. One can visit this address to see the illustrations.
 155 Address for elasticsearch is http://[ipaddr]:9200. One can use any Rest Tool to visit the testing data stored in elasticsearch.
 156
 157 Cleaning Up Environment
 158 -----------------------
 159
 160 .. code-block:: bash
 161
 162     . rm_virt_env.sh
 163
 164
 165 If you want to clean the dockers that established during the test, you can excute the additional commands below.
 166
 167 .. code-block:: bash
 168
 169     bash run_tests.sh --cleanup
 170
 171 Note that you can also add cleanup parameter when you run a test case. Then environment will be automatically cleaned up when
 172 completing the test.
 173
 174 Run POSCA through Community CI
 175 ==============================
 176 POSCA test cases are runned by OPNFV CI now. See https://build.opnfv.org for details of the building jobs.
 177 Each building job is set up to execute a single test case. The test results/logs will be printed on the web page and
 178 reported automatically to community MongoDB. There are two ways to report the results.
 179
 180 1. Report testing result by shell script
 181
 182 .. code-block:: bash
 183
 184     bash run_tests.sh [-h|--help] -s <testsuite>|-c <testcase> --report
 185
 186 2. Report testing result by python interpreter
 187
 188 .. code-block:: bash
 189
 190     REPORT=True
 191     opts="--privileged=true -id"
 192     docker_volume="-v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp"
 193     docker run $opts --name bottlenecks-load-master $docker_volume opnfv/bottlenecks:latest /bin/bash
 194     sleep 5
 195     REPORT="True"
 196     POSCA_SCRIPT="/home/opnfv/bottlenecks/testsuites/posca"
 197     docker exec bottlenecks_load-master python ${POSCA_SCRIPT}/../run_posca.py testcase|teststory <testcase> ${REPORT}
 198
 199 Test Result Description
 200 =======================
 201 * Please refer to release notes and also https://wiki.opnfv.org/display/testing/Result+alignment+for+ELK+post-processing