docs/com/pres/framework/framework.md

   1 # Functest Framework
   2
   3 created by [Cédric Ollivier](mailto:cedric.ollivier@orange.com)
   4
   5 2017/05/06
   6
   7 Note:
   8
   9 - Functest integrates lots of heterogeneous 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 attributes
  37     - all common operations
  38     - the status codes expected
  39 - avoid duplicating codes between testcases
  40 - ease the development 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 - result
  55 - start_time
  56 - stop_time
  57 - details
  58
  59
  60 ### methods
  61
  62 | Method            | Purpose                                    |
  63 |-------------------|--------------------------------------------|
  64 | run(**kwargs)     | run the test case                          |
  65 | is_successful()   | interpret the results of the test case     |
  66 | get_duration()    | return the duration of the test case       |
  67 | push_to_db()      | push the results of the test case to the DB|
  68
  69
  70 ### run(**kwargs)
  71
  72 - the subclasses must override the default implementation which is false on purpose
  73 - the new implementation must set the following attributes to push the results to DB:
  74     - result
  75     - start_time
  76     - stop_time
  77
  78
  79 ### class attributes
  80
  81 | Status code        | Returned when       |
  82 |--------------------|---------------------|
  83 | EX_OK              | everything is OK    |
  84 | EX_RUN_ERROR       | run() failed        |
  85 | EX_TESTCASE_FAILED | results are false   |
  86 | EX_PUSH_TO_DB_ERROR| push_to_db() failed |
  87
  88
  89 ### run_tests.py
  90
  91 ```python
  92 module = importlib.import_module(run_dict['module'])
  93 cls = getattr(module, run_dict['class'])
  94 test_dict = ft_utils.get_dict_by_test(test_name)
  95 test_case = cls(**test_dict)
  96 try:
  97     kwargs = run_dict['args']
  98     result = test_case.run(**kwargs)
  99 except KeyError:
 100     result = test_case.run()
 101 if result == testcase.TestCase.EX_OK:
 102     if GlobalVariables.REPORT_FLAG:
 103         test_case.push_to_db()
 104     result = test_case.is_successful()
 105 duration = test_case.get_duration()
 106 ```
 107
 108
 109
 110 ## Your first test case
 111
 112
 113 ### first.py
 114
 115 ```python
 116 #!/usr/bin/env python
 117
 118 import time
 119
 120 from functest.core import testcase
 121
 122 class Test(testcase.TestCase):
 123
 124     def run(self, **kwargs):
 125         self.start_time = time.time()
 126         print "Hello World"
 127         self.result = 100
 128         self.stop_time = time.time()
 129         return testcase.TestCase.EX_OK
 130 ```
 131
 132
 133 ### functest/ci/testcases.yaml
 134
 135 ```yaml
 136 case_name: first
 137 project_name: functest
 138 criteria: 100
 139 blocking: true
 140 clean_flag: false
 141 description: ''
 142 dependencies:
 143     installer: ''
 144     scenario: ''
 145 run:
 146     module: 'first'
 147     class: 'Test'
 148 ```
 149
 150
 151
 152 ## class Feature
 153 bases: TestCase
 154
 155 base model for single feature
 156
 157
 158 ### methods
 159
 160 | Method            | Purpose                   |
 161 |-------------------|---------------------------|
 162 | run(**kwargs)     | run the feature           |
 163 | execute(**kwargs) | execute the Python method |
 164
 165
 166 ### run(**kwargs)
 167
 168 - allows executing any Python method by calling execute()
 169 - sets the following attributes required to push the results to DB:
 170     - result
 171     - start_time
 172     - stop_time
 173 - doesn't fulfill details when pushing the results to the DB.
 174
 175
 176 ### execute(**kwargs)
 177
 178 - the subclasses must override the default implementation which is false on purpose
 179 - the new implementation must return 0 if success or anything else if failure.
 180
 181
 182
 183 ## Your second test case
 184
 185
 186 ### second.py
 187
 188 ```python
 189 #!/usr/bin/env python
 190
 191 from functest.core import feature
 192
 193 class Test(feature.Feature):
 194
 195     def execute(self, **kwargs):
 196         print "Hello World"
 197         return 0
 198 ```
 199
 200
 201 ### functest/ci/testcases.yaml
 202
 203 ```yaml
 204 case_name: second
 205 project_name: functest
 206 criteria: 100
 207 blocking: true
 208 clean_flag: false
 209 description: ''
 210 dependencies:
 211     installer: ''
 212     scenario: ''
 213 run:
 214     module: 'second'
 215     class: 'Test'
 216 ```
 217
 218
 219
 220 ## class BashFeature
 221 bases: Feature
 222
 223 class designed to run any bash command
 224
 225
 226 ### execute(**kwargs)
 227
 228 execute the cmd passed as arg.
 229
 230
 231
 232 ## Your third test case
 233
 234
 235 ### functest/ci/testcases.yaml
 236
 237 ```
 238 case_name: third
 239 project_name: functest
 240 criteria: 100
 241 blocking: true
 242 clean_flag: false
 243 description: ''
 244 dependencies:
 245     installer: ''
 246     scenario: ''
 247 run:
 248     module: 'functest.core.feature'
 249     class: 'BashFeature'
 250     args:
 251         cmd: 'echo Hello World; exit 0'
 252 ```
 253
 254
 255
 256 ## Euphrates
 257
 258
 259 ### Next actions
 260
 261 - __to finish VNF abstraction (coverage + pylint)__
 262 - to publish doc API
 263 - to manage criteria as written in testcases.yaml
 264
 265 Please see [Functest Euphrates page](https://wiki.opnfv.org/display/functest/Functest+Euphrates+page) for more details
 266
 267
 268
 269 ## Thank You!