Update requirements-dev.txt based on osmclient and IM requirements
[osm/tests.git] / 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   - `cluster_heal`: `heal_01`, `heal_02`, `heal_03`, `heal_04`
184   - `cluster_sol003`: `sol003_01`
185 - daily: for all testsuites that will run in the daily job
186 - regression: for all testsuites that should pass in the current stable branch
187 - sanity: for all testsuites that should be passed by each commit in the
188   stage3 to be successfully verified by Jenkins, currently `basic_07`,
189   `basic_11`, `k8s_03`, `k8s_04`, `sa_02`, `hackfest_basic`, `hackfest_cloudinit`
190
191 In addition, the tag "cleanup" exists in those tests that perform
192 any deletion. In that way, it can be invoked to retry the deletion if
193 the tests were forcefully stopped.
194
195 - For helping in the migration tests and other scenarios in which you don't want
196 to destroy the deployments immediately, the following tags are used:
197   - prepare: for the tests that are used to deploy the network
198   services under test
199   - verify: for the tests that perform the actual testing, or changes for
200   additional verifications (e.g. scaling).
201   - cleanup: already described above.
202
203   So, for instance, you could first deploy a number of network services executing
204   the tests with "prepare" tag, migrate to another OSM version, and then
205   check the behavior executing with the "verify" tag. Finally, use the "cleanup"
206   tag. 
207
208 ## Post-processing Robot output files
209
210 The output files of Robot include tyipically three files:
211
212 - `report.html`: overview of the test execution results in HTML format
213 - `log.html`: details about the executed test cases in HTML format
214 - `output.xml`: all the test execution results in machine readable XML format
215
216 More information about these files [here](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#output-file).
217
218 It is possible to use the tool `rebot`, included as part of the Robot Framework, to post-process the output file `output.xml`.
219
220 ```bash
221 # To re-generate log and report from output.xml:
222 rebot [-d <output_folder>] output.xml
223
224 # To re-generate log and report (and optionally new output.xml) to include only certain tags:
225 rebot [-d <output_folder>] -i <tag1> -i <tag2> ... -i <tagN> [-o <new_output_xml>] output.xml
226
227 # To re-generate log and report (and optionally new output.xml) excluding certain tags:
228 rebot [-d <output_folder>] -e <tag1> -e <tag2> ... -e <tagN> [-o <new_output_xml>] output.xml
229
230 # To merge several test executions:
231 rebot [-d <output_folder>] --merge output1.xml output2.xml ... outputN.xml
232 ```
233
234 More information about post-processing Robot output files [here](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#post-processing-outputs)
235
236 ## Built With
237
238 * [Python](www.python.org/) - The language used
239 * [Robot Framework](robotframework.org) - The testing framework
240
241 ## Contributing
242
243 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
244
245 ## Versioning
246
247 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).
248
249 ## License
250
251 This project is licensed under the Apache2 License - see the [LICENSE.md](LICENSE) file for details
252