Documentation/contributor/regressions.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @node Regression tests
   3 @chapter Regression tests
   4
   5 @menu
   6 * Introduction to regression tests::
   7 * Precompiled regression tests::
   8 * Compiling regression tests::
   9 * Identifying code regressions::
  10 * Memory and coverage tests::
  11 * MusicXML tests::
  12 @end menu
  13
  14
  15 @node Introduction to regression tests
  16 @section Introduction to regression tests
  17
  18 LilyPond has a complete suite of regression tests that are used
  19 to ensure that changes to the code do not break existing behavior.
  20 These regression tests comprise small LilyPond snippets that test
  21 the functionality of each part of LilyPond.
  22
  23 Regression tests are added when new functionality is added to
  24 LilyPond.  They are also added when bugs are identified.  The
  25 snippet that causes the bug becomes a regression test to verify
  26 that the bug has been fixed.
  27
  28 The regression tests are compiled using special @code{make}
  29 targets.  There are three primary uses for the regression
  30 tests.  First, successful completion of the regression tests means
  31 that LilyPond has been properly built.  Second, the output of the
  32 regression tests can be manually checked to ensure that
  33 the graphical output matches the description of the intended
  34 output.  Third, the regression test output from two different
  35 versions of LilyPond can be automatically compared to identify
  36 any differences.  These differences should then be manually
  37 checked to ensure that the differences are intended.
  38
  39 Regression tests (@qq{regtests}) are available in precompiled form
  40 as part of the documentation.  Regtests can also be compiled
  41 on any machine that has a properly configured LilyPond build
  42 system.
  43
  44
  45 @node Precompiled regression tests
  46 @section Precompiled regression tests
  47
  48 @subheading Regression test output
  49
  50 As part of the release process, the regression tests are run
  51 for every LilyPond release.  Full regression test output is
  52 available for every stable version and the most recent development
  53 version.
  54
  55 Regression test output is available in HTML and PDF format.  Links
  56 to the regression test output are available at the developer's
  57 resources page for the version of interest.
  58
  59 The latest stable version of the regtests is found at:
  60
  61 @example
  62 @uref{http://lilypond.org/doc/stable/input/regression/collated-files.html}
  63 @end example
  64
  65 The latest development version of the regtests is found at:
  66
  67 @example
  68 @uref{http://lilypond.org/doc/latest/input/regression/collated-files.html}
  69 @end example
  70
  71
  72 @subheading Regression test comparison
  73
  74 Each time a new version is released, the regtests are
  75 compiled and the output is automatically compared with the
  76 output of the previous release.  The result of these
  77 comparisons is archived online:
  78
  79 @example
  80 @uref{http://lilypond.org/test/}
  81 @end example
  82
  83 Checking these pages is a very important task for the LilyPond project.
  84 You are invited to report anything that looks broken, or any case
  85 where the output quality is not on par with the previous release,
  86 as described in @rweb{Bug reports}.
  87
  88 @warning{ The special regression test
  89 @file{test-output-distance.ly} will always show up as a
  90 regression.  This test changes each time it is run, and serves to
  91 verify that the regression tests have, in fact, run.}
  92
  93
  94 @subheading What to look for
  95
  96 The test comparison shows all of the changes that occurred between
  97 the current release and the prior release.  Each test that has a
  98 significant difference in output is displayed, with the old
  99 version on the left and the new version on the right.
 100
 101 Regression tests whose output is the same for both versions are
 102 not shown in the test comparison.
 103
 104 @itemize
 105 @item
 106 Images: green blurs in the new version show the approximate
 107 location of elements in the old version.
 108
 109 There are often minor adjustments in spacing which do not indicate
 110 any problem.
 111
 112 @item
 113 Log files: show the difference in command-line output.
 114
 115 The main thing to examine are any changes in page counts -- if a
 116 file used to fit on 1 page but now requires 4 or 5 pages,
 117 something is suspicious!
 118
 119 @item
 120 Profile files: give information about
 121 TODO?  I don't know what they're for.
 122
 123 @end itemize
 124
 125 @warning{
 126 The automatic comparison of the regtests checks the LilyPond
 127 bounding boxes.  This means that Ghostscript changes and changes
 128 in lyrics or text are not found.
 129 }
 130
 131 @node Compiling regression tests
 132 @section Compiling regression tests
 133
 134 Developers may wish to see the output of the complete regression
 135 test suite for the current version of the source repository
 136 between releases.  Current source code is available; see
 137 @ref{Working with source code}.  Then you will need
 138 to build the LilyPond binary; see @ref{Compiling LilyPond}.
 139
 140 Uninstalling the previous LilyPond version is not necessary, nor is
 141 running @code{make install}, since the tests will automatically be
 142 compiled with the LilyPond binary you have just built in your source
 143 directory.
 144
 145 From this point, the regtests are compiled with:
 146
 147 @example
 148 make test
 149 @end example
 150
 151 If you have a multi-core machine you may want to use the @option{-j}
 152 option and @var{CPU_COUT} variable, as
 153 described in @ref{Saving time with CPU_COUNT}.
 154 For a quad-core processor the complete command would be:
 155
 156 @example
 157 make -j5 CPU_COUNT=5 test
 158 @end example
 159
 160 The regtest output will then be available in
 161 @file{input/regression/out-test}.
 162 @file{input/regression/out-test/collated-examples.html}
 163 contains a listing of all the regression tests that were run,
 164 but none of the images are included.  Individual images are
 165 also available in this directory.
 166
 167 The primary use of @samp{make@tie{}test} is to verify that the
 168 regression tests all run without error.  The regression test
 169 page that is part of the documentation is created only when the
 170 documentation is built, as described in @ref{Generating documentation}.
 171 Note that building the documentation requires more installed components
 172 than building the source code, as described in
 173 @ref{Requirements for building documentation}.
 174
 175
 176 @node Identifying code regressions
 177 @section Identifying code regressions
 178
 179 Before modified code is committed to master, a regression test
 180 comparison must be completed to ensure that the changes have
 181 not caused problems with previously working code.  The comparison
 182 is made automatically upon compiling the regression test suite
 183 twice.
 184
 185 @enumerate
 186
 187 @item
 188 Before making changes, a baseline should be established by
 189 running:
 190
 191 @example
 192 make test-baseline
 193 @end example
 194
 195 @item
 196 Make your changes, or apply the patch(es) to consider.
 197
 198 @item
 199 Check for unintentional changes to the regtests:
 200
 201 @example
 202 make check
 203 @end example
 204
 205 After this has finished, a regression test comparison will be
 206 available at:
 207
 208 @example
 209 out/test-results/index.html
 210 @end example
 211
 212 For each regression test that differs between the baseline and the
 213 changed code, a regression test entry will displayed.  Ideally,
 214 the only changes would be the changes that you were working on.
 215 If regressions are introduced, they must be fixed before
 216 committing the code.
 217
 218 @warning{
 219 The special regression test @file{test-output-distance.ly} will always
 220 show up as a regression.  This test changes each time it is run, and
 221 serves to verify that the regression tests have, in fact, run.}
 222
 223 @item
 224 If you are happy with the results, then stop now.
 225
 226 If you want to continue programming, then make any additional code
 227 changes, and continue.
 228
 229 @item
 230 To re-check files that differed between the initial
 231 @samp{make@tie{}test-baseline} and your post-changes
 232 @samp{make@tie{}check}, run:
 233
 234 @example
 235 make test-redo
 236 @end example
 237
 238 This updates the regression list at @file{out/test-results/index.html}.
 239 It does @emph{not} redo @file{test-output-distance.ly}.
 240
 241 @item
 242 When all regressions have been resolved, the output list will be empty.
 243
 244 @item
 245 Once all regressions have been resolved, a final check should be completed
 246 by running:
 247
 248 @example
 249 make test-clean
 250 make check
 251 @end example
 252
 253 This cleans the results of the previous @samp{make@tie{}check}, then does the
 254 automatic regression comparison again.
 255
 256 @end enumerate
 257
 258
 259 @node Memory and coverage tests
 260 @section Memory and coverage tests
 261
 262 In addition to the graphical output of the regression tests, it is
 263 possible to test memory usage and to determine how much of the source
 264 code has been exercised by the tests.
 265
 266 @subheading Memory usage
 267
 268 For tracking memory usage as part of this test, you will need
 269 GUILE CVS; especially the following patch:
 270 @uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
 271
 272 @subheading Code coverage
 273
 274 For checking the coverage of the test suite, do the following
 275
 276 @example
 277 ./scripts/auxiliar/build-coverage.sh
 278 @emph{# uncovered files, least covered first}
 279 ./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
 280 @emph{# consecutive uncovered lines, longest first}
 281 ./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
 282 @end example
 283
 284
 285 @node MusicXML tests
 286 @section MusicXML tests
 287
 288
 289 LilyPond comes with a complete set of regtests for the
 290 @uref{http://www.musicxml.org/,MusicXML} language.  Originally
 291 developed to test @samp{musicxml2ly}, these regression tests
 292 can be used to test any MusicXML implementation.
 293
 294 The MusicXML regression tests are found at
 295 @file{input/regression/musicxml/}.
 296
 297 The output resulting from running these tests
 298 through @samp{muscxml2ly} followed by @samp{lilypond} is
 299 available in the LilyPond documentation:
 300
 301 @example
 302 @uref{http://lilypond.org/doc/latest/input/regression/musicxml/collated-files}
 303 @end example
 304