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 It should look like this::
 126
 127   ---
 128   - project:
 129       name: openflowplugin-csit-flow-services
 130       jobs:
 131         - '{project}-csit-1node-{functionality}-{install}-{stream}'
 132
 133       # The project name
 134       project: 'openflowplugin'
 135
 136       # The functionality under test
 137       functionality: 'flow-services'
 138
 139       # Project branches
 140       stream:
 141         - carbon:
 142             branch: 'master'
 143             jre: 'openjdk8'
 144
 145       install:
 146         - only:
 147             scope: 'only'
 148         - all:
 149             scope: 'all'
 150
 151       # Features to install
 152       install-features: >
 153           odl-openflowplugin-flow-services-ui,
 154           odl-openflowplugin-app-bulk-o-matic
 155
 156       # Robot custom options
 157       robot-options: '-v ODL_OF_PLUGIN:lithium'
 158
 159 Explanation:
 160
 161 * name: give some name like $project-csit-$functionality.
 162 * jobs: replace 1node by 3node if your test is develop for 3node cluster.
 163 * project: set your your project name here (e.g. openflowplugin).
 164 * functionality: set the functionality you want to test (e.g. flow-services).
 165   Note this has also to match the robot test plan name you defined in the earlier
 166   section `<Create a test plan_>`_ (e.g. openflowplugin-flow-services.txt)
 167 * stream: list the project branches you are going to generate system test. Only
 168   last branch if the project is new.
 169 * install: this specifies controller installation, 'only' means only features in
 170   install-features will be installed, 'all' means all compatible features will
 171   be installed on top (multi-project features test).
 172 * install-features: list of features you want to install in controller separated
 173   by comma.
 174 * robot-options: robot option you want to pass to the test separated by space.
 175
 176 Save the changes and exit editor.
 177
 178 Optional: Change default tools image
 179 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 180 By default a system test spins a tools VM that can be used to run some test tool
 181 like mininet, netconf tool, BGP simulator, etc. The default values are listed
 182 below and you only need to specify them if you are changing something, for
 183 example "tools_system_count: 0" will skip the tools VM if you do not need it.
 184 For a list of available images see images-list_::
 185
 186   ---
 187   - project:
 188       name: openflowplugin-csit-flow-services
 189       jobs:
 190         - '{project}-csit-1node-{functionality}-{install}-{stream}'
 191
 192       # The project name
 193       project: 'openflowplugin'
 194
 195       # The functionality under test
 196       functionality: 'flow-services'
 197
 198       # Project branches
 199       stream:
 200         - carbon:
 201             branch: 'master'
 202             jre: 'openjdk8'
 203
 204       install:
 205         - only:
 206             scope: 'only'
 207         - all:
 208             scope: 'all'
 209
 210       # Job images (optional)
 211       tools_system_count: 1
 212       tools_system_flavor: 2 GB General Purpose v1
 213       tools_system_image: Ubuntu 14.04 - mininet - 20170210-0439
 214
 215       # Features to install
 216       install-features: >
 217           odl-openflowplugin-flow-services-ui,
 218           odl-openflowplugin-app-bulk-o-matic
 219
 220       # Robot custom options
 221       robot-options: '-v ODL_OF_PLUGIN:lithium'
 222
 223
 224 Optional: Plot a graph from your job
 225 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 226 Scalability and peformance tests not only PASS/FAIL but most important they
 227 provide a number or value we want to plot in a graph and track over different
 228 builds.
 229
 230 For that you can add the plot configuration like in this example below::
 231
 232   ---
 233   - project:
 234       name: openflowplugin-csit-cbench-performance
 235       jobs:
 236         - '{project}-csit-1node-{functionality}-{install}-{stream}'
 237
 238       # The project name
 239       project: 'openflowplugin'
 240
 241       # The functionality under test
 242       functionality: 'cbench-performance'
 243
 244       # Project branches
 245       stream:
 246         - carbon:
 247             branch: 'master'
 248             jre: 'openjdk8'
 249         - boron:
 250             branch: 'stable/boron'
 251             jre: 'openjdk8'
 252
 253       install:
 254         - only:
 255             scope: 'only'
 256
 257       # Features to install
 258       install-features: 'odl-openflowplugin-flow-services-ui,odl-openflowplugin-drop-test'
 259
 260       # Robot custom options
 261       robot-options: '-v throughput_threshold:20000 -v latency_threshold:5000'
 262
 263       # Plot Info
 264       01-plot-title: 'Throughput Mode'
 265       01-plot-yaxis: 'flow_mods/sec'
 266       01-plot-group: 'Cbench Performance'
 267       01-plot-data-file: 'throughput.csv'
 268       02-plot-title: 'Latency Mode'
 269       02-plot-yaxis: 'flow_mods/sec'
 270       02-plot-group: 'Cbench Performance'
 271       02-plot-data-file: 'latency.csv'
 272
 273 Explanation:
 274
 275 * There are up to 10 plots per job and every plot can track different values,
 276   for example max, min, average recorded in a csv file. In the example above you
 277   can skip the 02-* lines if you do not use second plot.
 278 * plot-title: title for your plot.
 279 * plot-yaxis: your measurement (xaxis is build # so no need to fill).
 280 * plot-group: just a label, use the same in case you have 2 plots.
 281 * plot-data-file: this is the csv file generated by robot framework and contains
 282   the values to plot. Examples can be found in openflow-performance_.
 283
 284 Optional: Add Patch Test Job to verify project patches
 285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 286 With the steps above your new csit job will run daily on latest generated
 287 distribution. There is one more extra and optional step if you also want to run
 288 your system test to verify patches in your project.
 289
 290 The patch test is triggered in gerrit using the keyword::
 291
 292   test-$project-$feature
 293
 294 The job will:
 295
 296 * Build the gerrit patch.
 297 * Create a distribution containing the patch.
 298 * Trigger some system test (csit) that already exists and you specify with the
 299   $feature definition below.
 300
 301 Create $project-patch-test.yaml file in your jjb folder::
 302
 303   vim jjb/$project/$project-patch-test-jobs.yaml
 304
 305 Fill the information as below::
 306
 307   ---
 308   - project:
 309       name: openflowplugin-patch-test
 310       jobs:
 311           - '{project}-patch-test-{feature}-{stream}'
 312
 313       # The project name
 314       project: 'openflowplugin'
 315
 316       # Project branches
 317       stream:
 318           - carbon:
 319               branch: 'master'
 320               jdk: 'openjdk8'
 321           - boron:
 322               branch: 'stable/boron'
 323               jdk: 'openjdk8'
 324
 325       feature:
 326           - core:
 327               csit-list: >
 328                   openflowplugin-csit-1node-flow-services-only-{stream},
 329                   openflowplugin-csit-1node-flow-services-all-{stream},
 330                   openflowplugin-csit-1node-scalability-only-{stream},
 331                   openflowplugin-csit-1node-cbench-performance-only-{stream},
 332                   openflowplugin-csit-1node-config-performance-only-{stream},
 333                   openflowplugin-csit-3node-clustering-only-{stream}
 334
 335           - netvirt:
 336               csit-list: >
 337                   netvirt-csit-1node-openstack-mitaka-gate-transparent-{stream}
 338
 339           - cluster-netvirt:
 340               csit-list: >
 341                   netvirt-csit-3node-openstack-mitaka-gate-transparent-{stream}
 342
 343 Explanation:
 344
 345 * name: give some name like $project-patch-test.
 346 * project: set your your project name here (e.g. openflowplugin).
 347 * stream: list the project branches you are going to generate system test. Only
 348   last branch if the project is new.
 349 * feature: you can group system tests in features. Note there is a predefined
 350   feature -all- that triggers all features together.
 351 * Fill the csit-list with all the system test jobs you want to run to verify a
 352   feature.
 353
 354 Debug System Test
 355 -----------------
 356 Before pushing your system test job into jenkins-releng_, it is recommended to
 357 debug the job as well as the you system test code in the sandbox. To do that:
 358
 359 * Set up sandbox access using jenkins-sandbox-install_ instruction.
 360 * Push your new csit job to sandbox:
 361
 362   Method 1:
 363
 364   you can write a comment in a releng/builder gerrit patch to have the job automatically created
 365   in the sandbox. The format of the comment is::
 366
 367       jjb-deploy <job name>
 368
 369   Method 2::
 370
 371       jenkins-jobs --conf jenkins.ini update jjb/ $project-csit-1node-$functionality-only-$branch
 372
 373 * Open your job in jenkins-sandbox_ and start a build replacing the PATCHREFSPEC
 374   parameter by your int/test patch REFSPEC (e.g. refs/changes/85/23185/1). you
 375   can find this info in gerrit top right corner 'Download' button.
 376 * Update the PATCHREFSPEC parameter every time you push a new patchset in the
 377   int/test repository.
 378
 379 Optional: Debug VM issues in sandbox
 380 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 381 In case of problems with the test VMs, you can easily debug these issues in the
 382 sandbox by adding the following lines in a Jenkins shell window::
 383
 384   cat > ${WORKSPACE}/debug-script.sh <<EOF
 385
 386   <<put your debug shell script here>>
 387
 388   EOF
 389   scp ${WORKSPACE}/debug-script.sh ${TOOLS_SYSTEM_IP}:/tmp
 390   ssh ${TOOLS_SYSTEM_IP} 'sudo bash /tmp/debug-script.sh'
 391
 392 Note this will run a self-made debug script with sudo access in a VM of your
 393 choice. In the example above you debug on the tools VM (TOOLS_SYSTEM_IP),
 394 use ODL_SYSTEM_IP to debug in controller VM.
 395
 396 Save and push JJB changes
 397 ^^^^^^^^^^^^^^^^^^^^^^^^^
 398 Once you are happy with your system test, save the changes and push them in the
 399 releng builder repo::
 400
 401   git add -A
 402   git commit -s
 403   git push
 404
 405 .. important::
 406
 407   If this is your first system test job, it is recommended to add the int/test
 408   patch (gerrit link) in the commit message so that committers can merge both
 409   the int/test and the releng/builder patches at the same time.
 410
 411 Check system test jobs in Jenkins
 412 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 413 Once your patches are merged your system test can be browsed in jenkins-releng_:
 414
 415 * $project-csit-1node-$functionality-only-$branch -> The single-feature test.
 416 * $project-csit-1node-$functionality-all-$branch -> The multi-project test.
 417 * $yourproject-patch-test-$feature-$branch -> Patch test job.
 418
 419 Note that jobs in jenkins-releng_ cannot be reconfigured, only jobs in
 420 jenkins-sandbox_ can, that is why it is so important for testers to get access
 421 to sandbox.
 422
 423 Support
 424 -------
 425 Integration people are happy to support with questions and recommendations:
 426
 427 * Integration IRC: OpenDaylight channel 'opendaylight-integration
 428 * Integration Mail: OpenDaylight list 'integration-dev@lists.opendaylight.org'
 429
 430 .. _pulling-and-pushing-the-code: http://docs.opendaylight.org/en/stable-boron/developer-guide/pulling-and-pushing-the-code-from-the-cli.html
 431 .. _images-list: http://docs.opendaylight.org/en/stable-boron/submodules/releng/builder/docs/jenkins.html#pool-odlpub-hot-heat-orchestration-templates
 432 .. _openflow-performance: https://git.opendaylight.org/gerrit/gitweb?p=integration/test.git;a=blob;f=csit/suites/openflowplugin/Performance/010_Cbench.robot
 433 .. _jenkins-releng: https://jenkins.opendaylight.org/releng/
 434 .. _jenkins-sandbox: https://jenkins.opendaylight.org/sandbox/
 435 .. _jenkins-sandbox-install: http://docs.opendaylight.org/en/stable-boron/submodules/releng/builder/docs/jenkins.html#jenkins-sandbox