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