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