git.sur5r.net Git - bacula/bacula/blob - regress/README.ctest

   1
   2 Bacula Regression Suite and CTest
   3 ==================================================================
   4
   5 Thanks to Frank Sweetser, the Bacula regression scripts have now been modified
   6 to use the ctest component of cmake.  The major gain from this, since Bacula
   7 already had a working test framework in place, is the ability to have the
   8 results of each test submitted to a centralized dashboard system.  All of the
   9 test results are aggregated and summarized, where all of the developers can
  10 quickly see how the regression tests are running.
  11 ====
  12
  13 How to Use CTest
  14 ==================================================================
  15
  16 For more complete documentation on ctest, go to:
  17
  18 http://www.cmake.org/Wiki/CMake#CTest
  19
  20 The first step is to install the cmake package, which includes ctest.  If your
  21 distribution does already package it, you can download it directly from the
  22 source:
  23
  24 http://www.cmake.org
  25
  26 Next, you must edit your regression config file and add a paramter called
  27 SITE_NAME to identify the machine running the tests.  Ideally, it should
  28 contain something to identify yourself to whoever is viewing the test results
  29 as well as something to allow you to identify which machine is running the
  30 tests, ie
  31
  32 SITE_NAME=kern-bacula-gumbie
  33
  34 Once you have cmake installed, you can perform one of two different kinds of
  35 runs to submit test results.  The most common kind will be Nightly runs.  A
  36 Nightly CTest backup will update the source directory (as defined by the
  37 BACULA_SOURCE setting in your config file) to the current version, run the
  38 specified list of tests, and submit all of the results to the server.  Note
  39 that all of the results in a given 24 hour period (starting at 9pm EST) are
  40 lumped together to appear as a single block, rather than each test showing up
  41 as a different run.
  42
  43 The simplest way to trigger a nightly run is to use one of the two provided
  44 scripts.  The nightly-all script will run all non root tests, both tape and
  45 disk based, while the nightly-disk script will run only the disk based tests.
  46 So, you can choose between the following scripts:
  47
  48  cd <regress>
  49  ./nightly-all         # does disk and tape testing
  50  ./nightly-disk        # disk only tests
  51
  52  ./experimental-all    # experimental disk and tape testing
  53  ./experimental-disk   # experimental disk testing
  54
  55 We recommend that you start with the ./experimental-disk runs so that
  56 you can check that everything is working fine.  Once that is done,
  57 try a nightly-xxx run.  The difference is the experimental runs are just
  58 that -- they are things where you are experimenting and it is expected that
  59 something might be broken (bad ctest configuration, experimental source
  60 code, ...), and nightly runs are not expected to fail.
  61
  62 If you are a developer and you have modified your local Git repository, you
  63 should be running the experimental tests -- they are designed for developers.
  64 If you do modify your local repository and commit it, then run a nightly
  65 test.
  66
  67 If you are just doing testing on a nightly basis (no development in your
  68 source repository), then please use the nightly tests.
  69
  70 All the old scripts (./do_all, do_file, all-non-root-tests, ...) manually
  71 run the tests outside of ctest.
  72
  73 Periodically, however, you may want to submit a single test separately from a
  74 weekly run.  This may be a test of a particular patch you're working on, or
  75 perhaps a new OS patch.  For these one-shot tests, you will want to manually
  76 run ctest in Experimental mode, something like:
  77
  78 REGRESS_DEBUG=1 ctest -D Experimental -R all-non-root:auto-label-test
  79
  80 The '-D Experimental' option tells ctest to submit the test results as
  81 Experimental instead of Nightly.  We reccomend you use the REGRESS_DEBUG
  82 environmental variable to ensure that any errors from the test are logged in
  83 the dashboard (all of the ctest wrapper scripts set it).  The '-R <pattern>'
  84 option gives ctest a regular expression.  Any tests with a name as defined in
  85 DartTestfile.txt that matches the pattern will be run.
  86
  87 Note that you must have run ./scripts/do_sed at least once already in order to
  88 use Experimental mode.
  89 ====
  90
  91 Updating and Building Within CTest:
  92 ==================================================================
  93 Before each Nightly run, ctest will automatically update the BACULA_SOURCE
  94 directory, and submit these updates along with the test results.  Any
  95 Experimental runs will not.
  96
  97 Before either type of run actually begins running tests, ctest will run the
  98 script scripts/update-ctest.  This script first compares the version of
  99 BUILD_SOURCE with that of the build/ directory.  If the two versions differ, or
 100 if the build/ directory does not exist, it will automatically run 'make setup'
 101 for you.
 102 ====
 103
 104 Viewing the Dashboard:
 105 ==================================================================
 106 You can view the dashboard at:
 107
 108 http://regress.bacula.org/index.php?project=bacula
 109
 110 Results will not be visible as soon as they are submitted to the server.
 111 Processing is currently done every 10 minutes, so you may have to wait up to 15
 112 minutes or so before your results show up.
 113 ====
 114
 115 Getting CTest running on Solaris (thanks to Robert Hartzell):
 116 ============================================================
 117 The regression is working in zone on opensolaris build 126
 118
 119  create a zone and install these pkg's:
 120     SUNWcmake, SUNWmysql5, SUNWlibm, gcc-dev
 121     SUNWgtar, SUNWgit, SUNWperl584usr,
 122     and most of SUNWgnu*
 123
 124  In the config file I edited the "WHICHDB=" line to read:
 125      WHICHDB="--with-mysql=/usr/mysql/5.0"
 126
 127  And then in the shell:
 128  $ export LDFLAGS="-L/usr/mysql/5.0/lib/mysql -R/usr/mysql/5.0/lib/mysql"
 129  $ PATH=/usr/gnu/bin:$PATH
 130
 131  When i first ran "make setup" it failed... couldn't create the database
 132  so I had to run /usr/mysql/5.0/bin/mysql -u root mysql and do this:
 133     grant all privileges on regress.* to ''@localhost;
 134     grant all privileges on regress.* to ''@"%";
 135 ====
 136
 137 CTest script details:
 138 =========================================================
 139 Email from Frank describing the flow when running a ctest and some of the
 140 problems that come up.
 141
 142 0. Start off with a local Git repository at version A, and the master
 143 repository at version B.
 144
 145 1. nightly-disk is started.
 146
 147 2. nightly-disk runs scripts/config_dart
 148
 149 3. config_dart runs scripts/create_sed
 150
 151 4. create_sed pulls bversion and bdate out of the current local repo, so gets
 152 version A values.
 153
 154 5. config_dart then creates DartConfiguration.tcl from the .in file, leaving a
 155 BuildName parameter of A.
 156
 157 6. nightly-disk then runs 'ctest -D Nightly'.  This implicitly tells ctest to
 158 perform Update, Configure, Build, Test, and Submit stages, in that order.
 159
 160 7. The Update stage runs 'git pull' on the local repository.  The local
 161 repository is now updated to version B from the master, but since the
 162 DartConfiguration.tcl file was already created and has not been updated, the
 163 Update.xml file has the version A BuildName still.
 164
 165 8. Next, the Configure stage runs.  Since the configure process is handled in
 166 tandem with the build process by 'make setup', this just calls /bin/true so as
 167 to not throw any false errors, and can effectively be treated as a no-op.
 168
 169 9. Next is the Build stage, which is handled by calling scripts/update-ctest.
 170
 171 10.  update-ctest checks the Git versions of regress/build vs BACULA_SOURCE.
 172 Since the two are different (regress/build is still version A, while
 173 BACULA_SOURCE has been updated to B) it calls 'make setup'.
 174
 175 11. 'make setup' copies BACULA_SOURCE to regress/build and configures and
 176 builds it.  It then calls scripts/do_sed
 177
 178 12. do_sed calls scripts/config_dart again.  Since regress/build has been
 179 updated to B, it regenerates DartConfiguration.tcl with a version B BuildName.
 180
 181 13. ctest now generates the Build.xml results file, but since BuildName was
 182 still A while this stage began, this is what appears in the XML BuildName.
 183
 184 14. Done with the Build stage, ctest moves on to the Test stage, where it
 185 actually calls the various test/ scripts as defined by DartTestfile.txt and
 186 filtered by the -R option.  At this point, since ctest is beginning a new
 187 stage, it appears to re-read DartConfiguration.tcl (I believe this is intended
 188 to allow ctest to bootstrap itself in a virgin cmake managed source code tree,
 189 where the test configuration should be generated by cmake).  The final
 190 Test.xml file, therefore, contains a version B BuildName string, as opposed to
 191 all previous steps, which have version A.
 192
 193 15. Finally, ctest flings the results at the dashboard.  The dashboard does
 194 ignores in what order or grouping XML files are submitted, and instead uses
 195 the site/buildname tuple to distinguish them (at least for Nightly runs, I'm
 196 not so sure about Experimental ones).  In this case, instead of one complete
 197 run, the dashboard sees two runs, one of which is Update through Make, and a
 198 second one which is Test only.
 199
 200 For a sample of the problem, take a look at the fsweetser 2.3 sqlite3 Nightly
 201 runs at
 202
 203 http://regress.bacula.org:8081/Bacula/Dashboard/Dashboard?trackid=29
 204
 205 The Update and Build information show up with a BuildName of
 206 bacula-2.3.10-26Feb08-Linux-sqlite3, then aftegit pull hit the Test
 207 information shows up with bacula-2.3.11-03Mar08-Linux-sqlite3.  (Ignore for
 208 the moment the fact my timestamps are at 6:59PM, rather than at 9PM where
 209 they're supposed to be; this seems to be a Fedora specific client side issue I
 210 haven't tracked down yet.)
 211
 212 Looking more closely at the test submitted to the public dashboard
 213 (http://public.kitware.com/dashboard.php), I get the impression that the
 214 BuildName parameter was misnamed, and intended to be treated more as a build
 215 platform name, rather than the name of the build being tested.  Rather than
 216 create a hook to tag the version being tested, everyone as far as I can tell
 217 just seems to rely on the timestamp of the test.
 218 ======
 219
 220 Important Note:
 221 ======================================================================
 222 NOTE !!!!!!!!! ctest can actually back out changes that have been made to
 223 your local source repository (this was true for SVN, but I (Kern) am
 224 not sure it is true now that we have switched to git).
 225
 226 As a consequence, it is probably better not to
 227 use a directory in which you are developing code for Nightly tests.  Seee the
 228 below explanation given by Frank Sweetser.
 229
 230 When a Nightly run is done, the timestamp is set to the last occurring
 231 instance of the time defined by the NightlyStartTime parameter.  The piece
 232 that I missed is that, in addition to using that timestamp for reporting to
 233 the dashboard, the update stage also uses that point in time to determine
 234 exactly which version of the repository to check out.
 235
 236 So if you make commit changes at 10PM EST, and then run a Nightly test run,
 237 the NightlyStartTime of 9PM EST will back out those changes in the local
 238 repository.  Any subsequent runs that are started at 9PM EST the following day
 239 or later will include them.  This implies to me that NightlyStartTime should
 240 be set such that you don't expect any developers to commit any changes in
 241 between NightlyStartTime and the time at which the ctest run actually starts.
 242
 243 The alternative is to make use of the Experimental track.  While it normally
 244 just uses the local source tree as is, you can manually have it update:
 245
 246 ctest -D ExperimentalUpdate
 247
 248 Unlike Nightly, this will update to whatever the latest version of the
 249 repository is.