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