test/common/README.md

   1 ## Introduction ##
   2 This dir contains most scripts needed for the auto-test environment. There are scripts with functions to adapt to the apis of the components of the Non-RT RIC; Policy Agent, A1 Controller and Ric (A1) simulator.
   3 Some of the scripts can also be used for other kinds of tests, for example basic tests.
   4
   5 ## Overview for common test scripts and files ##
   6
   7 `test_env.sh` \
   8 Common env variables for test in the auto-test dir. All configuration of port numbers, image names and version etc shall be made in this file.
   9 Used by the auto test scripts/suites but could be used for other test script as well.
  10
  11 `testcase_common.sh` \
  12 Common functions for auto test cases in the auto-test dir. This script is the foundation of test auto environment which sets up images and enviroment variables needed by this script as well as the script adapting to the APIs.
  13 The included functions are described in detail further below.
  14
  15 `testsuite_common.sh` \
  16 Common functions for running two or more auto test scripts as a suite.
  17
  18 `agent_api_functions.sh` \
  19 Contains functions for adapting towards the Policy Agent API, also via dmaap (using a message-router stub interface)
  20
  21 `controller_api_functions.sh` \
  22 Contains functions for adaping towards the A1-controller API.
  23
  24 `ricsimulator_api_functions.sh` \
  25 Contains functions for adapting towards the RIC (A1) simulator admin API.
  26
  27 `compare_json.py` \
  28 A python script to compare two json obects for equality. Note that the comparsion always sort json-arrays before comparing (that is, it does not care about the order of items within the array). In addition, the target json object may specify individual parameter values where equality is 'dont care'.
  29
  30 `count_json_elements.py` \
  31 A python script returning the number of items in a json array.
  32
  33 `create_policies_process.py` \
  34 A python script to create a batch of policies. The script is intended to run in a number of processes to create policies in parallel.
  35
  36 `create_rics_json.py` \
  37 A python script to create a json file from a formatted string of ric info. Helper for the test enviroment.
  38
  39 `delete_policies_process.py` \
  40 A python script to delete a batch of policies. The script is intended to run in a number of processes to delete policies in parallel.
  41
  42 `extract_sdnc_reply.py` \
  43 A python script to extract the information from an sdnc (A1 Controller) reply json. Helper for the test environment.
  44
  45 `do_curl_function.sh`
  46 A script for executing a curl call with a specific url and optional payload. It also compare the response with an expected result in terms of response code and optional returned payload. Intended to be used by test script (for example basic test scripts of other components)
  47
  48
  49
  50 ### Descriptions of functions in testcase_common.sh ###
  51
  52 #### Script args ####
  53 The script can be started with these arguments
  54
  55 | arg list |
  56 |--|
  57 | `local|remote|remote-remove [auto-clean] [--stop-at-error] [--use-local-image <app-nam> [<app-name>]*]` |
  58
  59 | parameter | description |
  60 |-|-|
  61 | `local` | only locally built images (in local docker respository) will be used for the Non-RT RIC components. CBS, Consul, DB will still use remote nexus images |
  62 | `remote` | only remote images from nexus will be used. Images pulled if not present in local docker repository |
  63 | `remote-remove` | same as remote but all images are removed first so that fresh images are pulled when running |
  64 | `auto-clean` | all containers will be automatically stopped and removed when the test case is complete. Requires the function 'auto_clean_containers' to be included last in the applicable auto-test script |
  65 | `--stop-at-error` | intended for debugging and make the script stop at first 'FAIL' and save all logs with a prefix 'STOP_AT_ERROR' |
  66 | `--use-local-image` | Only applicable when running as 'remote' or 'remote-remove'. Mainly for debugging when a locally built image shall be used together with other remote images from nexus.Accepts a space separated list of PA, CP, RICSIM, SDNC for Policy Agent, Control Panel, A1-controller and the Ric simulator |
  67
  68 #### Function: print_result ####
  69 Print a test report of an auto-test script.
  70 | arg list |
  71 |--|
  72 | None |
  73
  74 #### Function: start_timer ####
  75 Start a timer for time measurement. Only one timer can be running.
  76 | arg list |
  77 |--|
  78 | None - but any args will be printed (It is good practice to use same args for this function as for the `print_timer`) |
  79
  80 #### Function: print_timer ####
  81 Print the value of the timer (in seconds) previously started by 'start_timer'. (Note that timer is still running after this function). The result of the timer as well as the args to the function will also be printed in the test report.
  82 | arg list |
  83 |--|
  84 | `<timer-message-to-print>` |
  85
  86 | parameter | description |
  87 | --------- | ----------- |
  88 | `<timer-message-to-print>` | Any text message to be printed along with the timer result.(It is good practice to use same args for this function as for the `start_timer`) |
  89
  90 #### Function: print_and_reset_timer ####
  91 Print the value of the timer (in seconds) previously started by 'start_timer'. Also reset the timer to 0. The result of the timer as well as the args to the function will also be printed in the test report.
  92 | arg list |
  93 |--|
  94 | `<timer-message-to-print>` |
  95
  96 | parameter | description |
  97 | --------- | ----------- |
  98 | `<timer-message-to-print>` | Any text message to be printed along with the timer result.(It is good practice to use same args for this function as for the `start_timer`) |
  99
 100 #### Function: deviation ####
 101 Mark a test as a deviation from the requirements. The list of deviations will be printed in the test report.
 102 | arg list |
 103 |--|
 104 | `<deviation-message-to-print>` |
 105
 106 | parameter | description |
 107 | --------- | ----------- |
 108 | `<deviation-message-to-print>` | Any text message describing the deviation. The text will also be printed in the test report. The intention is to mark known deviations, compared to required functionality |
 109
 110 #### Function: clean_containers ####
 111 Stop and remove all containers. Containers not part of the test are not affected.
 112 | arg list |
 113 |--|
 114 | None |
 115
 116 #### Function: auto_clean_containers ####
 117 Stop and remove all containers. Containers not part of the test are not affected. This function has effect only if the test script is started with arg `auto-clean`. This intention is to use this function as the last step in an auto-test script.
 118 | arg list |
 119 |--|
 120 | None |
 121
 122 #### Function: sleep_wait ####
 123 Make the script sleep for a number of seconds.
 124 | arg list |
 125 |--|
 126 | `<sleep-time-in-sec> [<any-text-in-quotes-to-be-printed>]` |
 127
 128 | parameter | description |
 129 | --------- | ----------- |
 130 | `<sleep-time-in-sec> ` | Number of seconds to sleep |
 131 | `<any-text-in-quotes-to-be-printed>` | Optional. The text will be printed, if present |
 132
 133
 134
 135 #### Function: consul_config_app ####
 136 Function to load a json config from a file into consul for the Policy Agent
 137
 138 | arg list |
 139 |--|
 140 | `<json-config-file>` |
 141
 142 | parameter | description |
 143 | --------- | ----------- |
 144 | `<json-config-file>` | The path to the json file to be loaded to Consul/CBS |
 145
 146 #### Function: prepare_consul_config ####
 147 Function to prepare a Consul config based on the previously configured (and started simulators). Note that all simulator must be running and the test script has to configure if http or https shall be used for the components (this is done by the functions 'use_simulator_http', 'use_simulator_https', 'use_sdnc_http', 'use_sdnc_https', 'use_mr_http', 'use_mr_https')
 148 | arg list |
 149 |--|
 150 | `<deviation-message-to-print>` |
 151
 152 | parameter | description |
 153 | --------- | ----------- |
 154 | `SDNC|SDNC_ONAP|NOSDNC` | Configure based on a1-controller (SNDC), a1-adapter (SDNC_ONAP) or without a controller/adapter (NOSDNC) |
 155 | `<output-file>` | The path to the json output file containing the prepared config. This file is used in 'consul_config_app'  |
 156
 157 #### Function: start_consul_cbs ####
 158 Start the Consul and CBS containers
 159 | arg list |
 160 |--|
 161 | None |
 162
 163 #### Function: use_simulator_http ####
 164 Use http for all API calls (A1) toward the simulator. This is the default. Admin API calls to the simulator are not affected. Note that this function shall be called before preparing the config for Consul.
 165 | arg list |
 166 |--|
 167 | None |
 168
 169 #### Function: use_simulator_https ####
 170 Use https for all API calls (A1) toward the simulator. Admin API calls to the simulator are not affected. Note that this function shall be called before preparing the config for Consul.
 171 | arg list |
 172 |--|
 173 | None |
 174
 175 #### Function: start_ric_simulators ####
 176 Start a group of simulator where a group may contain 1 more simulators.
 177 | arg list |
 178 |--|
 179 | `ricsim_g1|ricsim_g2|ricsim_g3 <count> <interface-id>` |
 180
 181 | parameter | description |
 182 | --------- | ----------- |
 183 | `ricsim_g1|ricsim_g2|ricsim_g3` | Base name of the simulator. Each instance will have an postfix instance id added, starting on '1'. For examplle 'ricsim_g1_1', 'ricsim_g1_2' etc  |
 184 |`<count>`| And integer, 1 or greater. Specifies the number of simulators to start|
 185 |`<interface-id>`| Shall be the interface id of the simulator. See the repo 'a1-interface' for the available ids. |
 186
 187 #### Function: start_control_panel ####
 188 Start the Control Panel container
 189 | arg list |
 190 |--|
 191 | None |
 192
 193 #### Function: start_sdnc ####
 194 Start the SDNC A1 Controller container and its database container
 195 | arg list |
 196 |--|
 197 | None |
 198
 199 #### Function: use_sdnc_http ####
 200 Use http for all API calls towards the SDNC A1 Controller. This is the default. Note that this function shall be called before preparing the config for Consul.
 201 | arg list |
 202 |--|
 203 | None |
 204
 205 #### Function: use_sdnc_http ####
 206 Use https for all API calls towards the SDNC A1 Controller. Note that this function shall be called before preparing the config for Consul.
 207 | arg list |
 208 |--|
 209 | None |
 210
 211 #### Function: start_sdnc_onap ####
 212 Start the SDNC A1 Adapter container and its database container
 213 | arg list |
 214 |--|
 215 | None |
 216
 217 #### Function: config_sdnc_onap ####
 218 Configure the SDNC A1 adapter - Not implemented
 219 | arg list |
 220 |--|
 221 | None |
 222
 223 #### Function: start_mr ####
 224 Start the Message Router stub interface container
 225 | arg list |
 226 |--|
 227 | None |
 228
 229 #### Function: use_mr_http ####
 230 Use http for all Dmaap calls to the MR. This is the default. The admin API is not affected. Note that this function shall be called before preparing the config for Consul.
 231 | arg list |
 232 |--|
 233 | None |
 234
 235 #### Function: use_mr_https ####
 236 Use https for all Dmaap call to the MR. The admin API is not affected. Note that this function shall be called before preparing the config for Consul.
 237 | arg list |
 238 |--|
 239 | None |
 240
 241 #### Function: start_cr ####
 242 Start the Callback Receiver container
 243 | arg list |
 244 |--|
 245 | None |
 246
 247 #### Function: start_policy_agent ####
 248 Start the Policy Agent container. If the test script is configured to use a stand alone Policy Agent (for example other container or stand alone app) the script will prompt for starting the stand alone Policy Agent.
 249 | arg list |
 250 |--|
 251 | None |
 252
 253 #### Function: use_agent_stand_alone ####
 254 Configure to run the Policy Agent as a stand alone container or app. See also 'start_policy_agent'
 255 | arg list |
 256 |--|
 257 | None |
 258
 259 #### Function: use_agent_rest_http ####
 260 Use http for all API calls to the Policy Agent. This is the default.
 261 | arg list |
 262 |--|
 263 | None |
 264
 265 #### Function: use_agent_rest_https ####
 266 Use https for all API calls to the Policy Agent.
 267 | arg list |
 268 |--|
 269 | None |
 270
 271 #### Function: use_agent_dmaap ####
 272 Send and recieve all API calls to the Policy Agent over Dmaap via the MR.
 273 | arg list |
 274 |--|
 275 | None |
 276
 277 #### Function: set_agent_debug ####
 278 Configure the Policy Agent log on debug level. The Policy Agent must be running.
 279 | arg list |
 280 |--|
 281 | None |
 282
 283 #### Function: set_agent_trace ####
 284 Configure the Policy Agent log on trace level. The Policy Agent must be running.
 285 | arg list |
 286 |--|
 287 | None |
 288
 289 #### Function: use_agent_retries ####
 290 Configure the Policy Agent to make upto 5 retries if an API calls return any of the specified http return codes.
 291 | arg list |
 292 |--|
 293 | `[<response-code>]*` |
 294
 295 | parameter | description |
 296 | --------- | ----------- |
 297 | `[<response-code>]*` | A space separated list of http response codes, may be empty to reset to 'no codes'.  |
 298
 299 #### Function: check_policy_agent_logs ####
 300 Check the Policy Agent log for any warnings and errors and print the count of each.
 301 | arg list |
 302 |--|
 303 | None |
 304
 305 #### Function: check_control_panel_logs ####
 306 Check the Control Panel log for any warnings and errors and print the count of each.
 307 | arg list |
 308 |--|
 309 | None |
 310
 311 #### Function: store_logs ####
 312 Take a snap-shot of all logs for all running containers and stores them in `./logs/<ATC-id>`. All logs will get the specified prefix in the file name. In general, one of the last steps in an auto-test script shall be to call this function. If logs shall be taken several times during a test script, different prefixes shall be used each time.
 313 | arg list |
 314 |--|
 315 | `<logfile-prefix>` |
 316
 317 | parameter | description |
 318 | --------- | ----------- |
 319 | `<logfile-prefix>` | Log file prefix  |
 320
 321
 322 #### Function: cr_equal ####
 323 TBD
 324
 325 #### Function: mr_equal ####
 326 TBD
 327
 328 #### Function: mr_greater ####
 329 TBD
 330
 331 #### Function: mr_read ####
 332 TBD
 333
 334 #### Function: mr_print ####
 335 TBD
 336
 337 ### Descriptions of functions in testsuite_common.sh ###
 338 TBD
 339 ### Descriptions of functions in agent_api_function.sh ###
 340 TBD
 341 ### Descriptions of functions in ricsimulator_api_functions.sh ###
 342 TBD
 343 ### Descriptions of functions in controller_api_functions.sh ###
 344 TBD
 345
 346 ## License
 347
 348 Copyright (C) 2020 Nordix Foundation. All rights reserved.
 349 Licensed under the Apache License, Version 2.0 (the "License");
 350 you may not use this file except in compliance with the License.
 351 You may obtain a copy of the License at
 352
 353      http://www.apache.org/licenses/LICENSE-2.0
 354
 355 Unless required by applicable law or agreed to in writing, software
 356 distributed under the License is distributed on an "AS IS" BASIS,
 357 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 358 See the License for the specific language governing permissions and
 359 limitations under the License.