docs/system-test-guide.rst

   1 System Test Guide
   2 =================
   3
   4 Introduction
   5 ------------
   6 This step by step guide aims to help projects with the task of creating a
   7 System Test job that runs in Continuous Integration.
   8
   9 A System Test job will normally install a controller distribution in one or
  10 more VMs and will run a functionality test using some test tool (e.g. mininet).
  11 This job will run periodically, tipically once or twice a day.
  12
  13 All projects defining top-level features (essential functionality) and that have
  14 decided to use the OpenDaylight CI for system test must create system test jobs.
  15
  16 System test jobs rely on Robot Framework, this is because Robot FW provides:
  17
  18 * Structure for test creation and execution (e.g. test suites, test cases that
  19   PASS/FAIL).
  20 * Easy test debug (real time logs, etc...).
  21 * Test reports in Jenkins.
  22
  23 For those projects creating system test, Integration group will provide:
  24
  25 * Robot Framework support and assistance.
  26 * Review of system test code. The code will be pushed to integration/test git
  27   (csit/suites/$project/).
  28 * JJB templates to install controller and execute a robot test to verify a
  29   project functionality (releng/builder git, jjb/integration/).
  30
  31 Create basic system test
  32 ------------------------
  33 Download Integration/Test Repository::
  34
  35   git clone ssh://${USERNAME}@git.opendaylight.org:29418/integration/test.git
  36   cd test
  37
  38 Follow the instructions in pulling-and-pushing-the-code_ to know more about
  39 pulling and pushing code.
  40
  41 Create a folder for your project robot test::
  42
  43   mkdir test/csit/suites/$project
  44   cd test/csit/suites/$project
  45
  46 Replace $project with your project name.
  47
  48 Move your robot suites (test folders) into the project folder:
  49
  50 If you do not have any robot test yet, copy integration basic folder suite into
  51 your folder. You can later improve this suite or replace it by your own suites::
  52
  53   cp -R test/csit/suites/integration/basic basic
  54
  55 This suite will verify Restconf is operational.
  56
  57 Create a test plan
  58 ^^^^^^^^^^^^^^^^^^
  59 A test plan is a text file indicating which robot test suites (including
  60 integration repo path) will be executed to test a project functionality::
  61
  62   vim test/csit/testplans/$project-$functionality.txt
  63
  64 Replace $project with your project name and $functionality with the
  65 functionality you want to test.
  66
  67 If you took the basic test from integration, the test plan file should look
  68 like this::
  69
  70   # Place the suites in run order:
  71   integration/test/csit/suites/$project/basic
  72
  73 Save the changes and exit editor.
  74
  75 Optional: Version specific test plan
  76 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  77 Integration/Test is not part of the simultaneous release, so the same suites are
  78 used for testing all supported ODL versions. There may be API changes between
  79 different releases of ODL, which may require different logic in your Robot
  80 tests. If the difference is small, it is recommended to act upon value of
  81 ODL_STREAM variable (e.g. "beryllium", "boron", "carbon", etc).
  82
  83 If the difference is big, you may want to use different list of suites in
  84 testplan. One way is to define separate jobs with different functionality names.
  85 But the more convenient way is to define stream-specific testplan. For example::
  86
  87   vim test/csit/testplans/$project-$functionality-boron.txt
  88
  89 would contain a list of suites for testing Boron, while
  90 $project-$functionality.txt would still contain the default list (used for
  91 streams without stream specific testplans).
  92
  93 Optional: Create a script or config plan
  94 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  95 Sometimes the environment prepared by scripts in releng/builder is not suitable
  96 as is, and there are changes to be done before controller is installed (script
  97 plan) or before it is started (config plan). You may create as many bash scripts
  98 as you need in test/csit/scripts/ and then list them in the scriplans or
  99 configplans folder::
 100
 101   vim test/csit/scriptplans/$project-$functionality.txt
 102
 103 Save and push Test changes
 104 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 105 Add the changes and push them in the integration/test repo::
 106
 107   git add -A
 108   git commit -s
 109   git push
 110
 111 Create system test job
 112 ----------------------
 113 Download RelEng Builder repository::
 114
 115   git clone ssh://${USERNAME}@git.opendaylight.org:29418/releng/builder
 116   cd builder
 117
 118 Follow the instructions in pulling-and-pushing-the-code_ to know more about
 119 pulling and pushing code.
 120
 121 Create a new file and modify the values according to your project::
 122
 123   vim jjb/$project/$project-csit-$functionality.yaml
 124
 125 For a Managed project it should look like this::
 126
 127   ---
 128   - project:
 129       name: openflowplugin-csit-flow-services
 130       jobs:
 131         - inttest-csit-1node
 132
 133       # The project name
 134       project: 'openflowplugin'
 135
 136       # The functionality under test
 137       functionality:
 138         - flow-services
 139         - gate-flow-services
 140
 141       # Project branches
 142       stream:
 143         - fluorine:
 144             branch: 'master'
 145         - oxygen:
 146             branch: 'stable/oxygen'
 147         - nitrogen:
 148             branch: 'stable/nitrogen'
 149         - carbon:
 150             branch: 'stable/carbon'
 151             karaf-version: 'karaf3'
 152
 153       install:
 154         - all:
 155             scope: 'all'
 156
 157       # Features to install
 158       install-features: >
 159           odl-openflowplugin-flow-services-rest,
 160           odl-openflowplugin-app-table-miss-enforcer,
 161           odl-openflowplugin-nxm-extensions
 162
 163       # Robot custom options
 164       robot-options: ''
 165
 166 Explanation:
 167
 168 * name: give some name like $project-csit-$functionality.
 169 * jobs: replace 1node by 3node if your test is develop for 3node cluster.
 170 * project: set your your project name here (e.g. openflowplugin).
 171 * functionality: set the functionality you want to test (e.g. flow-services).
 172   Note this has also to match the robot test plan name you defined in the earlier
 173   section `<Create a test plan_>`_ (e.g. openflowplugin-flow-services.txt)
 174 * stream: list the project branches you are going to generate system test. Only
 175   last branch if the project is new.
 176 * install: this specifies controller installation, 'only' means only features in
 177   install-features will be installed, 'all' means all compatible features will
 178   be installed on top (multi-project features test).
 179 * install-features: list of features you want to install in controller separated
 180   by comma.
 181 * robot-options: robot option you want to pass to the test separated by space.
 182
 183 Self-Managed projects
 184 ^^^^^^^^^^^^^^^^^^^^^
 185
 186 For Self-Managed project, we need 2 extra parameters:
 187
 188 * trigger-jobs: Self-Managed CSIT will run after succesful project merge, so just
 189   fill with '{project}-merge-{stream}'.
 190 * repo-url: Self-Managed project feature repository maven URL (see example below).
 191
 192 So in this case it should look like this::
 193
 194   ---
 195   - project:
 196       name: usc-csit-channel
 197       jobs:
 198         - inttest-csit-1node
 199
 200       # The project name
 201       project: 'usc'
 202
 203       # The functionality under test
 204       functionality: 'channel'
 205
 206       # Project branches
 207       stream:
 208         - fluorine:
 209             branch: 'master'
 210             trigger-jobs: '{project}-merge-{stream}'
 211             # yamllint disable-line rule:line-length
 212             repo-url: 'mvn:org.opendaylight.usc/usc-features/1.6.0-SNAPSHOT/xml/features'
 213
 214       install:
 215         - all:
 216             scope: 'all'
 217
 218       # Features to install
 219       install-features: 'odl-restconf,odl-mdsal-apidocs,odl-usc-channel-ui'
 220
 221       # Robot custom options
 222       robot-options: ''
 223
 224 Save the changes and exit editor.
 225
 226 Optional: Change default tools image
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 228 By default a system test spins a tools VM that can be used to run some test tool
 229 like mininet, netconf tool, BGP simulator, etc. The default values are listed
 230 below and you only need to specify them if you are changing something, for
 231 example "tools_system_count: 0" will skip the tools VM if you do not need it.
 232 For a list of available images see images-list_::
 233
 234   ---
 235   - project:
 236       name: openflowplugin-csit-flow-services
 237       jobs:
 238         - inttest-csit-1node
 239
 240       # The project name
 241       project: 'openflowplugin'
 242
 243       # The functionality under test
 244       functionality:
 245         - flow-services
 246         - gate-flow-services
 247
 248       # Project branches
 249       stream:
 250         - fluorine:
 251             branch: 'master'
 252         - oxygen:
 253             branch: 'stable/oxygen'
 254         - nitrogen:
 255             branch: 'stable/nitrogen'
 256         - carbon:
 257             branch: 'stable/carbon'
 258             karaf-version: 'karaf3'
 259
 260       install:
 261         - all:
 262             scope: 'all'
 263
 264       # Job images
 265       tools_system_image: 'ZZCI - Ubuntu 16.04 - mininet-ovs-28 - 20180301-1041'
 266
 267       # Features to install
 268       install-features: >
 269           odl-openflowplugin-flow-services-rest,
 270           odl-openflowplugin-app-table-miss-enforcer,
 271           odl-openflowplugin-nxm-extensions
 272
 273       # Robot custom options
 274       robot-options: ''
 275
 276 Optional: Plot a graph from your job
 277 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 278 Scalability and peformance tests not only PASS/FAIL but most important they
 279 provide a number or value we want to plot in a graph and track over different
 280 builds.
 281
 282 For that you can add the plot configuration like in this example below::
 283
 284   ---
 285   - project:
 286       name: openflowplugin-csit-cbench
 287       jobs:
 288         - inttest-csit-1node
 289
 290       # The project name
 291       project: 'openflowplugin'
 292
 293       # The functionality under test
 294       functionality: 'cbench'
 295
 296       # Project branches
 297       stream:
 298         - fluorine:
 299             branch: 'master'
 300         - oxygen:
 301             branch: 'stable/oxygen'
 302         - nitrogen:
 303             branch: 'stable/nitrogen'
 304         - carbon:
 305             branch: 'stable/carbon'
 306             karaf-version: 'karaf3'
 307
 308       install:
 309         - only:
 310             scope: 'only'
 311
 312       # Job images
 313       tools_system_image: 'ZZCI - Ubuntu 16.04 - mininet-ovs-28 - 20180301-1041'
 314
 315       # Features to install
 316       install-features: 'odl-openflowplugin-flow-services-rest,odl-openflowplugin-drop-test'
 317
 318       # Robot custom options
 319       robot-options: '-v duration_in_secs:60 -v throughput_threshold:20000 -v latency_threshold:5000'
 320
 321       # Plot Info
 322       01-plot-title: 'Throughput Mode'
 323       01-plot-yaxis: 'flow_mods/sec'
 324       01-plot-group: 'Cbench Performance'
 325       01-plot-data-file: 'throughput.csv'
 326       02-plot-title: 'Latency Mode'
 327       02-plot-yaxis: 'flow_mods/sec'
 328       02-plot-group: 'Cbench Performance'
 329       02-plot-data-file: 'latency.csv'
 330
 331 Explanation:
 332
 333 * There are up to 10 plots per job and every plot can track different values,
 334   for example max, min, average recorded in a csv file. In the example above you
 335   can skip the 02-* lines if you do not use second plot.
 336 * plot-title: title for your plot.
 337 * plot-yaxis: your measurement (xaxis is build # so no need to fill).
 338 * plot-group: just a label, use the same in case you have 2 plots.
 339 * plot-data-file: this is the csv file generated by robot framework and contains
 340   the values to plot. Examples can be found in openflow-performance_.
 341
 342 Optional: Add Patch Test Job to verify project patches
 343 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 344 With the steps above your new csit job will run daily on latest generated
 345 distribution. There is one more extra and optional step if you also want to run
 346 your system test to verify patches in your project.
 347
 348 The patch test is triggered in gerrit using the keyword::
 349
 350   test-$project-$feature
 351
 352 The job will:
 353
 354 * Build the gerrit patch.
 355 * Create a distribution containing the patch.
 356 * Trigger some system test (csit) that already exists and you specify with the
 357   $feature definition below.
 358
 359 Create $project-patch-test.yaml file in your jjb folder::
 360
 361   vim jjb/$project/$project-patch-test-jobs.yaml
 362
 363 Fill the information as below::
 364
 365   ---
 366   - project:
 367       name: openflowplugin-patch-test
 368       jobs:
 369         - inttest-patch-test
 370
 371       # The project name
 372       project: 'openflowplugin'
 373
 374       # Project branches
 375       stream:
 376         - fluorine:
 377             branch: 'master'
 378             os-branch: 'queens'
 379         - oxygen:
 380             branch: 'stable/oxygen'
 381             os-branch: 'queens'
 382         - nitrogen:
 383             branch: 'stable/nitrogen'
 384             os-branch: 'pike'
 385         - carbon:
 386             branch: 'stable/carbon'
 387             os-branch: 'ocata'
 388             karaf-version: 'karaf3'
 389
 390       jdk: 'openjdk8'
 391
 392       feature:
 393         - core:
 394             csit-list: >
 395                 openflowplugin-csit-1node-gate-flow-services-all-{stream},
 396                 openflowplugin-csit-1node-gate-scale-only-{stream},
 397                 openflowplugin-csit-1node-gate-perf-stats-collection-only-{stream},
 398                 openflowplugin-csit-1node-gate-perf-bulkomatic-only-{stream},
 399                 openflowplugin-csit-3node-gate-clustering-only-{stream},
 400                 openflowplugin-csit-3node-gate-clustering-bulkomatic-only-{stream},
 401                 openflowplugin-csit-3node-gate-clustering-perf-bulkomatic-only-{stream}
 402
 403 Explanation:
 404
 405 * name: give some name like $project-patch-test.
 406 * project: set your your project name here (e.g. openflowplugin).
 407 * stream: list the project branches you are going to generate system test. Only
 408   last branch if the project is new.
 409 * feature: you can group system tests in features. Note there is a predefined
 410   feature -all- that triggers all features together.
 411 * Fill the csit-list with all the system test jobs you want to run to verify a
 412   feature.
 413
 414 Debug System Test
 415 -----------------
 416 Before pushing your system test job into jenkins-releng_, it is recommended to
 417 debug the job as well as the you system test code in the sandbox. To do that:
 418
 419 * Set up sandbox access using jenkins-sandbox-install_ instruction.
 420 * Push your new csit job to sandbox:
 421
 422   Method 1:
 423
 424   you can write a comment in a releng/builder gerrit patch to have the job automatically created
 425   in the sandbox. The format of the comment is::
 426
 427       jjb-deploy <job name>
 428
 429   Method 2::
 430
 431       jenkins-jobs --conf jenkins.ini update jjb/ $project-csit-1node-$functionality-only-$branch
 432
 433 * Open your job in jenkins-sandbox_ and start a build replacing the PATCHREFSPEC
 434   parameter by your int/test patch REFSPEC (e.g. refs/changes/85/23185/1). you
 435   can find this info in gerrit top right corner 'Download' button.
 436 * Update the PATCHREFSPEC parameter every time you push a new patchset in the
 437   int/test repository.
 438
 439 Optional: Debug VM issues in sandbox
 440 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 441 In case of problems with the test VMs, you can easily debug these issues in the
 442 sandbox by adding the following lines in a Jenkins shell window::
 443
 444   cat > ${WORKSPACE}/debug-script.sh <<EOF
 445
 446   <<put your debug shell script here>>
 447
 448   EOF
 449   scp ${WORKSPACE}/debug-script.sh ${TOOLS_SYSTEM_IP}:/tmp
 450   ssh ${TOOLS_SYSTEM_IP} 'sudo bash /tmp/debug-script.sh'
 451
 452 Note this will run a self-made debug script with sudo access in a VM of your
 453 choice. In the example above you debug on the tools VM (TOOLS_SYSTEM_IP),
 454 use ODL_SYSTEM_IP to debug in controller VM.
 455
 456 Save and push JJB changes
 457 ^^^^^^^^^^^^^^^^^^^^^^^^^
 458 Once you are happy with your system test, save the changes and push them in the
 459 releng builder repo::
 460
 461   git add -A
 462   git commit -s
 463   git push
 464
 465 .. important::
 466
 467   If this is your first system test job, it is recommended to add the int/test
 468   patch (gerrit link) in the commit message so that committers can merge both
 469   the int/test and the releng/builder patches at the same time.
 470
 471 Check system test jobs in Jenkins
 472 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 473 Once your patches are merged your system test can be browsed in jenkins-releng_:
 474
 475 * $project-csit-1node-$functionality-only-$branch -> The single-feature test.
 476 * $project-csit-1node-$functionality-all-$branch -> The multi-project test.
 477 * $yourproject-patch-test-$feature-$branch -> Patch test job.
 478
 479 Note that jobs in jenkins-releng_ cannot be reconfigured, only jobs in
 480 jenkins-sandbox_ can, that is why it is so important for testers to get access
 481 to sandbox.
 482
 483 Support
 484 -------
 485 Integration people are happy to support with questions and recommendations:
 486
 487 * Integration IRC: OpenDaylight channel 'opendaylight-integration
 488 * Integration Mail: OpenDaylight list 'integration-dev@lists.opendaylight.org'
 489
 490 .. _pulling-and-pushing-the-code: http://docs.opendaylight.org/en/stable-boron/developer-guide/pulling-and-pushing-the-code-from-the-cli.html
 491 .. _images-list: http://docs.opendaylight.org/en/stable-boron/submodules/releng/builder/docs/jenkins.html#pool-odlpub-hot-heat-orchestration-templates
 492 .. _openflow-performance: https://git.opendaylight.org/gerrit/gitweb?p=integration/test.git;a=blob;f=csit/suites/openflowplugin/Performance/010_Cbench.robot
 493 .. _jenkins-releng: https://jenkins.opendaylight.org/releng/
 494 .. _jenkins-sandbox: https://jenkins.opendaylight.org/sandbox/
 495 .. _jenkins-sandbox-install: http://docs.opendaylight.org/en/stable-boron/submodules/releng/builder/docs/jenkins.html#jenkins-sandbox