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 For Unmanaged project, we need 2 extra parameters:
 184
 185 * trigger-jobs: Unmanaged CSIT will run after succesful project merge, so just
 186   fill with '{project}-merge-{stream}'.
 187 * bundle-url: Unmanaged CSIT uses project local distribution, you can get the
 188   local distribution URL from the Jenkins merge job itself (see example below).
 189
 190 So in this case it should look like this::
 191
 192   ---
 193   - project:
 194       name: usc-csit-channel
 195       jobs:
 196         - inttest-csit-1node
 197
 198       # The project name
 199       project: 'usc'
 200
 201       # The functionality under test
 202       functionality: 'channel'
 203
 204       # Project branches
 205       stream:
 206         - fluorine:
 207             branch: 'master'
 208             trigger-jobs: '{project}-merge-{stream}'
 209             # yamllint disable-line rule:line-length
 210             bundle-url: 'https://jenkins.opendaylight.org/releng/view/usc/job/usc-merge-fluorine/lastBuild/org.opendaylight.usc$usc-karaf/artifact/org.opendaylight.usc/usc-karaf/1.6.0-SNAPSHOT/usc-karaf-1.6.0-SNAPSHOT.zip'
 211
 212       install:
 213         - all:
 214             scope: 'all'
 215
 216       # Features to install
 217       install-features: 'odl-restconf,odl-mdsal-apidocs,odl-usc-channel-ui'
 218
 219       # Robot custom options
 220       robot-options: ''
 221
 222 Save the changes and exit editor.
 223
 224 Optional: Change default tools image
 225 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 226 By default a system test spins a tools VM that can be used to run some test tool
 227 like mininet, netconf tool, BGP simulator, etc. The default values are listed
 228 below and you only need to specify them if you are changing something, for
 229 example "tools_system_count: 0" will skip the tools VM if you do not need it.
 230 For a list of available images see images-list_::
 231
 232   ---
 233   - project:
 234       name: openflowplugin-csit-flow-services
 235       jobs:
 236         - inttest-csit-1node
 237
 238       # The project name
 239       project: 'openflowplugin'
 240
 241       # The functionality under test
 242       functionality:
 243         - flow-services
 244         - gate-flow-services
 245
 246       # Project branches
 247       stream:
 248         - fluorine:
 249             branch: 'master'
 250         - oxygen:
 251             branch: 'stable/oxygen'
 252         - nitrogen:
 253             branch: 'stable/nitrogen'
 254         - carbon:
 255             branch: 'stable/carbon'
 256             karaf-version: 'karaf3'
 257
 258       install:
 259         - all:
 260             scope: 'all'
 261
 262       # Job images
 263       tools_system_image: 'ZZCI - Ubuntu 16.04 - mininet-ovs-28 - 20180301-1041'
 264
 265       # Features to install
 266       install-features: >
 267           odl-openflowplugin-flow-services-rest,
 268           odl-openflowplugin-app-table-miss-enforcer,
 269           odl-openflowplugin-nxm-extensions
 270
 271       # Robot custom options
 272       robot-options: ''
 273
 274 Optional: Plot a graph from your job
 275 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 276 Scalability and peformance tests not only PASS/FAIL but most important they
 277 provide a number or value we want to plot in a graph and track over different
 278 builds.
 279
 280 For that you can add the plot configuration like in this example below::
 281
 282   ---
 283   - project:
 284       name: openflowplugin-csit-cbench
 285       jobs:
 286         - inttest-csit-1node
 287
 288       # The project name
 289       project: 'openflowplugin'
 290
 291       # The functionality under test
 292       functionality: 'cbench'
 293
 294       # Project branches
 295       stream:
 296         - fluorine:
 297             branch: 'master'
 298         - oxygen:
 299             branch: 'stable/oxygen'
 300         - nitrogen:
 301             branch: 'stable/nitrogen'
 302         - carbon:
 303             branch: 'stable/carbon'
 304             karaf-version: 'karaf3'
 305
 306       install:
 307         - only:
 308             scope: 'only'
 309
 310       # Job images
 311       tools_system_image: 'ZZCI - Ubuntu 16.04 - mininet-ovs-28 - 20180301-1041'
 312
 313       # Features to install
 314       install-features: 'odl-openflowplugin-flow-services-rest,odl-openflowplugin-drop-test'
 315
 316       # Robot custom options
 317       robot-options: '-v duration_in_secs:60 -v throughput_threshold:20000 -v latency_threshold:5000'
 318
 319       # Plot Info
 320       01-plot-title: 'Throughput Mode'
 321       01-plot-yaxis: 'flow_mods/sec'
 322       01-plot-group: 'Cbench Performance'
 323       01-plot-data-file: 'throughput.csv'
 324       02-plot-title: 'Latency Mode'
 325       02-plot-yaxis: 'flow_mods/sec'
 326       02-plot-group: 'Cbench Performance'
 327       02-plot-data-file: 'latency.csv'
 328
 329 Explanation:
 330
 331 * There are up to 10 plots per job and every plot can track different values,
 332   for example max, min, average recorded in a csv file. In the example above you
 333   can skip the 02-* lines if you do not use second plot.
 334 * plot-title: title for your plot.
 335 * plot-yaxis: your measurement (xaxis is build # so no need to fill).
 336 * plot-group: just a label, use the same in case you have 2 plots.
 337 * plot-data-file: this is the csv file generated by robot framework and contains
 338   the values to plot. Examples can be found in openflow-performance_.
 339
 340 Optional: Add Patch Test Job to verify project patches
 341 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 342 With the steps above your new csit job will run daily on latest generated
 343 distribution. There is one more extra and optional step if you also want to run
 344 your system test to verify patches in your project.
 345
 346 The patch test is triggered in gerrit using the keyword::
 347
 348   test-$project-$feature
 349
 350 The job will:
 351
 352 * Build the gerrit patch.
 353 * Create a distribution containing the patch.
 354 * Trigger some system test (csit) that already exists and you specify with the
 355   $feature definition below.
 356
 357 Create $project-patch-test.yaml file in your jjb folder::
 358
 359   vim jjb/$project/$project-patch-test-jobs.yaml
 360
 361 Fill the information as below::
 362
 363   ---
 364   - project:
 365       name: openflowplugin-patch-test
 366       jobs:
 367         - inttest-patch-test
 368
 369       # The project name
 370       project: 'openflowplugin'
 371
 372       # Project branches
 373       stream:
 374         - fluorine:
 375             branch: 'master'
 376             os-branch: 'queens'
 377         - oxygen:
 378             branch: 'stable/oxygen'
 379             os-branch: 'queens'
 380         - nitrogen:
 381             branch: 'stable/nitrogen'
 382             os-branch: 'pike'
 383         - carbon:
 384             branch: 'stable/carbon'
 385             os-branch: 'ocata'
 386             karaf-version: 'karaf3'
 387
 388       jdk: 'openjdk8'
 389
 390       feature:
 391         - core:
 392             csit-list: >
 393                 openflowplugin-csit-1node-gate-flow-services-all-{stream},
 394                 openflowplugin-csit-1node-gate-scale-only-{stream},
 395                 openflowplugin-csit-1node-gate-perf-stats-collection-only-{stream},
 396                 openflowplugin-csit-1node-gate-perf-bulkomatic-only-{stream},
 397                 openflowplugin-csit-3node-gate-clustering-only-{stream},
 398                 openflowplugin-csit-3node-gate-clustering-bulkomatic-only-{stream},
 399                 openflowplugin-csit-3node-gate-clustering-perf-bulkomatic-only-{stream}
 400
 401         - netvirt:
 402             csit-list: >
 403                 netvirt-csit-1node-openstack-{os-branch}-gate-stateful-{stream}
 404
 405         - cluster-netvirt:
 406             csit-list: >
 407                 netvirt-csit-3node-openstack-{os-branch}-gate-stateful-{stream}
 408
 409 Explanation:
 410
 411 * name: give some name like $project-patch-test.
 412 * project: set your your project name here (e.g. openflowplugin).
 413 * stream: list the project branches you are going to generate system test. Only
 414   last branch if the project is new.
 415 * feature: you can group system tests in features. Note there is a predefined
 416   feature -all- that triggers all features together.
 417 * Fill the csit-list with all the system test jobs you want to run to verify a
 418   feature.
 419
 420 Debug System Test
 421 -----------------
 422 Before pushing your system test job into jenkins-releng_, it is recommended to
 423 debug the job as well as the you system test code in the sandbox. To do that:
 424
 425 * Set up sandbox access using jenkins-sandbox-install_ instruction.
 426 * Push your new csit job to sandbox:
 427
 428   Method 1:
 429
 430   you can write a comment in a releng/builder gerrit patch to have the job automatically created
 431   in the sandbox. The format of the comment is::
 432
 433       jjb-deploy <job name>
 434
 435   Method 2::
 436
 437       jenkins-jobs --conf jenkins.ini update jjb/ $project-csit-1node-$functionality-only-$branch
 438
 439 * Open your job in jenkins-sandbox_ and start a build replacing the PATCHREFSPEC
 440   parameter by your int/test patch REFSPEC (e.g. refs/changes/85/23185/1). you
 441   can find this info in gerrit top right corner 'Download' button.
 442 * Update the PATCHREFSPEC parameter every time you push a new patchset in the
 443   int/test repository.
 444
 445 Optional: Debug VM issues in sandbox
 446 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 447 In case of problems with the test VMs, you can easily debug these issues in the
 448 sandbox by adding the following lines in a Jenkins shell window::
 449
 450   cat > ${WORKSPACE}/debug-script.sh <<EOF
 451
 452   <<put your debug shell script here>>
 453
 454   EOF
 455   scp ${WORKSPACE}/debug-script.sh ${TOOLS_SYSTEM_IP}:/tmp
 456   ssh ${TOOLS_SYSTEM_IP} 'sudo bash /tmp/debug-script.sh'
 457
 458 Note this will run a self-made debug script with sudo access in a VM of your
 459 choice. In the example above you debug on the tools VM (TOOLS_SYSTEM_IP),
 460 use ODL_SYSTEM_IP to debug in controller VM.
 461
 462 Save and push JJB changes
 463 ^^^^^^^^^^^^^^^^^^^^^^^^^
 464 Once you are happy with your system test, save the changes and push them in the
 465 releng builder repo::
 466
 467   git add -A
 468   git commit -s
 469   git push
 470
 471 .. important::
 472
 473   If this is your first system test job, it is recommended to add the int/test
 474   patch (gerrit link) in the commit message so that committers can merge both
 475   the int/test and the releng/builder patches at the same time.
 476
 477 Check system test jobs in Jenkins
 478 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 479 Once your patches are merged your system test can be browsed in jenkins-releng_:
 480
 481 * $project-csit-1node-$functionality-only-$branch -> The single-feature test.
 482 * $project-csit-1node-$functionality-all-$branch -> The multi-project test.
 483 * $yourproject-patch-test-$feature-$branch -> Patch test job.
 484
 485 Note that jobs in jenkins-releng_ cannot be reconfigured, only jobs in
 486 jenkins-sandbox_ can, that is why it is so important for testers to get access
 487 to sandbox.
 488
 489 Support
 490 -------
 491 Integration people are happy to support with questions and recommendations:
 492
 493 * Integration IRC: OpenDaylight channel 'opendaylight-integration
 494 * Integration Mail: OpenDaylight list 'integration-dev@lists.opendaylight.org'
 495
 496 .. _pulling-and-pushing-the-code: http://docs.opendaylight.org/en/stable-boron/developer-guide/pulling-and-pushing-the-code-from-the-cli.html
 497 .. _images-list: http://docs.opendaylight.org/en/stable-boron/submodules/releng/builder/docs/jenkins.html#pool-odlpub-hot-heat-orchestration-templates
 498 .. _openflow-performance: https://git.opendaylight.org/gerrit/gitweb?p=integration/test.git;a=blob;f=csit/suites/openflowplugin/Performance/010_Cbench.robot
 499 .. _jenkins-releng: https://jenkins.opendaylight.org/releng/
 500 .. _jenkins-sandbox: https://jenkins.opendaylight.org/sandbox/
 501 .. _jenkins-sandbox-install: http://docs.opendaylight.org/en/stable-boron/submodules/releng/builder/docs/jenkins.html#jenkins-sandbox