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