README.md

   1 <!--
   2 Copyright ETSI
   3
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7
   8    http://www.apache.org/licenses/LICENSE-2.0
   9
  10 Unless required by applicable law or agreed to in writing, software
  11 distributed under the License is distributed on an "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  13 implied.
  14 See the License for the specific language governing permissions and
  15 limitations under the License
  16 -->
  17
  18 # OSM test automation project - osm/tests
  19
  20 This repository contains tools and configuration files for testing and automation needs of OSM project.
  21
  22 ## Prerequisites
  23
  24 - OSM running
  25 - VIM already registered in OSM
  26 - K8s cluster already registered in OSM (for tests involving a K8s cluster)
  27
  28 ## Quickstart. How to run tests using OSM docker images
  29
  30 ### Configure the environment file
  31
  32 Create a file `envconfig.rc` copying from `envconfig-local.rc` and set the required variables.
  33
  34 ```
  35 OSM_HOSTNAME=<OSM_IP_ADDRESS>
  36 VIM_TARGET=<VIM_REGISTERED_AT_OSM>
  37 VIM_MGMT_NET=<NAME_OF_THE_MGMT_NETWORK_IN_THE_VIM>
  38 OS_CLOUD=<OPENSTACK_CLOUD>    # OpenStack Cloud defined in $HOME/.config/openstack/clouds.yaml or in /etc/openstack/clouds.yaml
  39 ```
  40
  41 ### Run the tests
  42
  43 ```bash
  44 docker run --rm=true --name tests -t --env-file envconfig.rc \
  45            -v ~/.config/openstack/clouds.yaml:/etc/openstack/clouds.yaml \
  46            -v ~/tests/reports:/robot-systest/reports \
  47            opensourcemano/tests:testing-daily \
  48            -t sanity
  49 ```
  50
  51 You can use a different robot tag instead of `sanity`. The whole list of tags are gathered below in this README.
  52
  53 ## How to build docker container for tests and run tests from there
  54
  55 ### Create the docker container
  56
  57 ```bash
  58 docker build -f docker/Dockerfile -t osmtests .
  59 ```
  60
  61 ### Run the tests
  62
  63 ```bash
  64 docker run --rm=true --name tests -t --env-file envconfig.rc \
  65            -v ~/.config/openstack/clouds.yaml:/etc/openstack/clouds.yaml \
  66            -v ~/tests/reports:/robot-systest/reports \
  67            osmtests \
  68            -t sol003_01
  69 ```
  70
  71 ## How to mount local tests folder for developing purposes
  72
  73 The following line will mount the folder `robot-systest`, including all libraries and testuites, and will execute the testsuite `sol003_01`:
  74
  75 ```bash
  76 docker run --rm=true --name tests -t --env-file envconfig.rc \
  77            -v ~/.config/openstack/clouds.yaml:/etc/openstack/clouds.yaml \
  78            -v ~/tests/robot-systest:/robot-systest \
  79            -v ~/tests/reports:/robot-systest/reports \
  80            -v ~/osm-packages:/robot-systest/osm-packages \
  81            opensourcemano/tests:testing-daily \
  82            -t sol003_01
  83 ```
  84
  85 Relevant volumes to be mounted are:
  86
  87 - <path_to_reports> [OPTIONAL]: the absolute path to reports location in the host
  88 - <path_to_clouds.yaml> [OPTIONAL]: the absolute path to the clouds.yaml file in the host
  89 - <path_to_sdncs.yaml> [OPTIONAL]: the absolute path to the sdncs.yaml file in the host
  90 - <path_to_kubeconfig> [OPTIONAL]: the kubeconfig file to be used for k8s clusters
  91
  92 Other relevant options to run tests are:
  93
  94 - `--env-file`: It is the environmental file where is described the OSM target and VIM
  95 - `-o <osmclient_version>` [OPTIONAL]: It is used to specify a particular osmclient version. Default: latest
  96 - `-p <package_branch>` [OPTIONAL]: OSM packages repository branch. Default: master
  97 - `-t <testing_tags>` [OPTIONAL]: Robot tests tags. [sanity, regression, particular_test]. Default: sanity
  98
  99 ## How to run tests from a host
 100
 101 In general, testing from docker images is the best way if you want to develop for OSM. However, sometimes it could be useful to run tests directly from the host.
 102
 103 ### Install dependencies
 104
 105 This bash script can be used to setup your environment to execute the tests.
 106
 107 ```bash
 108 sudo apt-get update
 109 sudo apt-get install ssh ping yq git
 110 # Python packages used for the tests
 111 python3 -m pip install -r requirements.txt
 112 python3 -m pip install -r requirements-dev.txt
 113 # Download community packages
 114 git clone https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages.git
 115 ```
 116
 117 ### Configure the environment
 118
 119 Create a file `envconfig.rc` copying from `envconfig-local.rc` and set the required variables (in this case, the use of `export` is mandatory).
 120
 121 ```
 122 export OSM_HOSTNAME=<OSM_IP_ADDRESS>
 123 export VIM_TARGET=<VIM_REGISTERED_AT_OSM>
 124 export VIM_MGMT_NET=<NAME_OF_THE_MGMT_NETWORK_IN_THE_VIM>
 125 export OS_CLOUD=<OPENSTACK_CLOUD>    # OpenStack Cloud defined in $HOME/.config/openstack/clouds.yaml or in /etc/openstack/clouds.yaml
 126 export K8S_CREDENTIALS= # path to the kubeconfig file of the K8s cluster to be tested
 127 ```
 128
 129 ### Running the tests
 130
 131 ```bash
 132 source envconfig.rc
 133 mkdir reports
 134 robot -d reports -i <testing_tags> testsuite/
 135 ```
 136
 137 ## How to run tests from an environment identical to OSM CICD
 138
 139 ```bash
 140 git clone https://osm.etsi.org/gerrit/osm/devops
 141 git clone https://osm.etsi.org/gerrit/osm/IM
 142 git clone https://osm.etsi.org/gerrit/osm/osmclient
 143 git clone https://osm.etsi.org/gerrit/osm/tests
 144 # run HTTP server to server artifacts
 145 devops/tools/local-build.sh --install-qhttpd
 146 # generate debian packages locally that will be served by the HTTP server
 147 devops/tools/local-build.sh --module IM,osmclient,tests stage-2
 148 # create docker image and store it locally as opensourcemano/tests:devel
 149 devops/tools/local-build.sh --module tests
 150 ```
 151
 152 Then, run the tests:
 153
 154 ```bash
 155 docker run --rm=true -t osmtests --env-file <env_file> \
 156        -v <path_to_reports>:/reports osmtests \
 157        -v <path_to_clouds.yaml>:/robot-systest/clouds.yaml \
 158        -v <path_to_sdncs.yaml>:/robot-systest/sdncs.yaml \
 159        -v <path_to_kubeconfig>:/root/.kube/config \
 160        -o <osmclient_version> \
 161        -p <package_branch> \
 162        -t <testing_tags>
 163 ```
 164
 165 ## Test tags
 166
 167 All tests in the testsuites have tags. Tags allow to run only a set of tests identified by a tag. Several tags can be specified when running robot in the following way:
 168
 169 ```bash
 170 robot -i <tag_01> -i <tag_02> testsuite/
 171 ```
 172
 173 The following tags exist for each testsuite:
 174
 175 - A tag per testsuite using its mnemonic (e.g. `basic_01`)
 176 - Cluster tag for each of the statistically similar tests:
 177   - `cluster_main`: `basic_01`, `basic_05`, `basic_08`, `basic_09`, `basic_15`,
 178     `basic_16`, `basic_17`, `hackfest_basic`, `hackfest_multivdu`,
 179     `hackfest_cloudinit`, `quotas_01`
 180   - `cluster_ee_config`: `basic_06`, `basic_07`, `basic_11`, `basic_12`,
 181     `basic_13`, `basic_14`, `k8s_05`, `k8s_06`
 182   - `cluster_relations`: `basic_11`, `basic_13`, `basic_14`
 183   - `cluster_epa`: `epa_01`, `epa_02`, `epa_03`, `epa_04`, `epa_05`
 184   - `cluster_k8s`: `k8s_01`, `k8s_02`, `k8s_03`, `k8s_04`, `k8s_05`, `k8s06`,
 185     `k8s_07`, `k8s_08`, `k8s_09`, `k8s_10`, `k8s_11`, `sa_08`
 186   - `cluster_k8s_charms`: `k8s_05`, `k8s_06`
 187   - `cluster_sa`: `sa_01`, `sa_02`, `sa_07`
 188   - `cluster_slices`: `slice_01`, `slice_02`
 189   - `cluster_heal`: `heal_01`, `heal_02`, `heal_03`, `heal_04`
 190   - `cluster_osm_rest`: `sol003_01`
 191 - daily: for all testsuites that will run in the daily job
 192 - regression: for all testsuites that should pass in the current stable branch
 193 - sanity: for all testsuites that should be passed by each commit in the
 194   stage3 to be successfully verified by Jenkins, currently `basic_07`,
 195   `basic_11`, `k8s_03`, `k8s_04`, `sa_02`, `hackfest_basic`, `hackfest_cloudinit`
 196
 197 In addition, the tag "cleanup" exists in those tests that perform
 198 any deletion. In that way, it can be invoked to retry the deletion if
 199 the tests were forcefully stopped.
 200
 201 - For helping in the migration tests and other scenarios in which you don't want
 202 to destroy the deployments immediately, the following tags are used:
 203   - `prepare`: for the tests that are used to deploy the network
 204   services under test
 205   - `verify`: for the tests that perform the actual testing, or changes for
 206   additional verifications (e.g. scaling).
 207   - `cleanup`: already described above.
 208
 209   So, for instance, you could first deploy a number of network services executing
 210   the tests with "prepare" tag, migrate to another OSM version, and then
 211   check the behavior executing with the "verify" tag. Finally, use the "cleanup"
 212   tag.
 213
 214 ## Post-processing Robot output files
 215
 216 The output files of Robot include tyipically three files:
 217
 218 - `report.html`: overview of the test execution results in HTML format
 219 - `log.html`: details about the executed test cases in HTML format
 220 - `output.xml`: all the test execution results in machine readable XML format
 221
 222 More information about these files [here](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#output-file).
 223
 224 It is possible to use the tool `rebot`, included as part of the Robot Framework, to post-process the output file `output.xml`.
 225
 226 ```bash
 227 # To re-generate log and report from output.xml:
 228 rebot [-d <output_folder>] output.xml
 229
 230 # To re-generate log and report (and optionally new output.xml) to include only certain tags:
 231 rebot [-d <output_folder>] -i <tag1> -i <tag2> ... -i <tagN> [-o <new_output_xml>] output.xml
 232
 233 # To re-generate log and report (and optionally new output.xml) excluding certain tags:
 234 rebot [-d <output_folder>] -e <tag1> -e <tag2> ... -e <tagN> [-o <new_output_xml>] output.xml
 235
 236 # To merge several test executions:
 237 rebot [-d <output_folder>] --merge output1.xml output2.xml ... outputN.xml
 238 ```
 239
 240 More information about post-processing Robot output files [here](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#post-processing-outputs)
 241
 242 ## Built With
 243
 244 * [Python](www.python.org/) - The language used
 245 * [Robot Framework](robotframework.org) - The testing framework
 246
 247 ## Contributing
 248
 249 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
 250
 251 ## Versioning
 252
 253 We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://osm.etsi.org/gitweb/?p=osm/tests.git;a=tags).
 254
 255 ## License
 256
 257 This project is licensed under the Apache2 License - see the [LICENSE](LICENSE) file for details
 258