docs/com/pres/framework/framework.md

   1 # Functest Framework
   2
   3 created by [Cédric Ollivier](mailto:cedric.ollivier@orange.com)
   4
   5 2017/04/24
   6
   7 Note:
   8
   9 - Functest integrates lots of heteregeounous testcases:
  10     - python vs bash
  11     - internal vs external
  12 - it aims to benefit from object programming
  13     - to define common operations
  14     - to avoid conditional instructions regarding the testcases
  15     - to avoid duplicating code
  16     - to ease the integration of third-party testcases (written in Bash or Python)
  17
  18
  19
  20 ## Quick overview
  21
  22
  23 ### Functest function calls
  24
  25 - **CI** calls *run_tests.py* (please see [jenkins jobs](https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=tree;f=jjb/functest))
  26 - *run_tests.py* parses *functest/ci/testcases.yaml* to:
  27     - check which testcase(s) must be run
  28     - execute the common operations on every testcase (run, push its results to db...)
  29 <!-- .element: class="fragment highlight-red"-->
  30     - return the right status code to **CI**
  31
  32
  33 ### Our target
  34
  35 - limit run_tests.py instructions by defining:
  36     - the basic testcase attritutes
  37     - all common operations
  38     - the status codes expected
  39 - avoid duplicating codes between testcases
  40 - ease the developpement of third-party testcases (aka features)
  41
  42
  43
  44 ## class TestCase
  45
  46 base model for single test case
  47
  48
  49 ### instance attributes
  50
  51 - project_name (default: 'functest')
  52 - case_name
  53 - criteria
  54 - start_time
  55 - stop_time
  56 - details
  57
  58
  59 ### methods
  60
  61 | Method            | Purpose                                    |
  62 |-------------------|--------------------------------------------|
  63 | run(**kwargs)     | run the test case                          |
  64 | check_criteria()  | interpret the results of the test case     |
  65 | push_to_db()      | push the results of the test case to the DB|
  66
  67
  68 ### run(**kwargs)
  69
  70 - the subclasses must override the default implementation which is false on purpose
  71 - the new implementation must set the following attributes to push the results to DB:
  72     - criteria
  73     - start_time
  74     - stop_time
  75
  76
  77 ### class attributes
  78
  79 | Status code        | Returned when       |
  80 |--------------------|---------------------|
  81 | EX_OK              | everything is OK    |
  82 | EX_RUN_ERROR       | run() failed        |
  83 | EX_TESTCASE_FAILED | results are false   |
  84 | EX_PUSH_TO_DB_ERROR| push_to_db() failed |
  85
  86
  87 ### run_tests.py
  88
  89 ```python
  90 module = importlib.import_module(run_dict['module'])
  91 cls = getattr(module, run_dict['class'])
  92 test_dict = ft_utils.get_dict_by_test(test_name)
  93 test_case = cls(**test_dict)
  94 try:
  95     kwargs = run_dict['args']
  96     result = test_case.run(**kwargs)
  97 except KeyError:
  98     result = test_case.run()
  99 if result == testcase.TestCase.EX_OK:
 100     if GlobalVariables.REPORT_FLAG:
 101         test_case.push_to_db()
 102     result = test_case.check_criteria()
 103 ```
 104
 105
 106
 107 ## Your first test case
 108
 109
 110 ### first.py
 111
 112 ```python
 113 #!/usr/bin/env python
 114
 115 import time
 116
 117 from functest.core import testcase
 118
 119 class Test(testcase.TestCase):
 120
 121     def run(self, **kwargs):
 122         self.start_time = time.time()
 123         print "Hello World"
 124         self.criteria = 'PASS'
 125         self.stop_time = time.time()
 126         return testcase.TestCase.EX_OK
 127 ```
 128
 129
 130 ### functest/ci/testcases.yaml
 131
 132 ```yaml
 133 case_name: first
 134 project_name: functest
 135 criteria: 'status == "PASS"'
 136 blocking: true
 137 clean_flag: false
 138 description: ''
 139 dependencies:
 140     installer: ''
 141     scenario: ''
 142 run:
 143     module: 'first'
 144     class: 'Test'
 145 ```
 146
 147
 148
 149 ## class Feature
 150 bases: TestCase
 151
 152 base model for single feature
 153
 154
 155 ### methods
 156
 157 | Method            | Purpose                   |
 158 |-------------------|---------------------------|
 159 | run(**kwargs)     | run the feature           |
 160 | execute(**kwargs) | execute the Python method |
 161
 162
 163 ### run(**kwargs)
 164
 165 - allows executing any Python method by calling execute()
 166 - sets the following attributes required to push the results to DB:
 167     - criteria
 168     - start_time
 169     - stop_time
 170 - doesn't fulfill details when pushing the results to the DB.
 171
 172
 173 ### execute(**kwargs)
 174
 175 - the subclasses must override the default implementation which is false on purpose
 176 - the new implementation must return 0 if success or anything else if failure.
 177
 178
 179
 180 ## Your second test case
 181
 182
 183 ### second.py
 184
 185 ```python
 186 #!/usr/bin/env python
 187
 188 from functest.core import feature
 189
 190 class Test(feature.Feature):
 191
 192     def execute(self, **kwargs):
 193         print "Hello World"
 194         return 0
 195 ```
 196
 197
 198 ### functest/ci/testcases.yaml
 199
 200 ```yaml
 201 case_name: second
 202 project_name: functest
 203 criteria: 'status == "PASS"'
 204 blocking: true
 205 clean_flag: false
 206 description: ''
 207 dependencies:
 208     installer: ''
 209     scenario: ''
 210 run:
 211     module: 'second'
 212     class: 'Test'
 213 ```
 214
 215
 216
 217 ## class BashFeature
 218 bases: Feature
 219
 220 class designed to run any bash command
 221
 222
 223 ### execute(**kwargs)
 224
 225 execute the cmd passed as arg.
 226
 227
 228
 229 ## Your third test case
 230
 231
 232 ### functest/ci/testcases.yaml
 233
 234 ```
 235 case_name: third
 236 project_name: functest
 237 criteria: 'status == "PASS"'
 238 blocking: true
 239 clean_flag: false
 240 description: ''
 241 dependencies:
 242     installer: ''
 243     scenario: ''
 244 run:
 245     module: 'functest.core.feature'
 246     class: 'BashFeature'
 247     args:
 248         cmd: 'echo Hello World; exit 0'
 249 ```
 250
 251
 252
 253 ## Euphrates
 254
 255
 256 ### Next actions
 257
 258 - __to finish VNF abstraction (coverage + pylint)__
 259 - to publish doc API
 260 - to manage criteria as written in testcases.yaml
 261
 262 Please see [Functest Euphrates page](https://wiki.opnfv.org/display/functest/Functest+Euphrates+page) for more details
 263
 264
 265
 266 ## Thank You!