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 The test comparison shows all of the changes that occured between
  84 the current release and the prior release.  Each test that has
  85 a significant difference in output is displayed, with the old
  86 version on the left and the new version on the right.  Blurs
  87 in the regression tests for the new version show the approximate
  88 location of elements in the old version.
  89
  90 Regression tests whose output is the same for both versions are not
  91 shown in the test comparison.
  92
  93 Checking these pages is a very important task for the LilyPond project.
  94 You are invited to report anything that looks broken, or any case
  95 where the output quality is not on par with the previous release,
  96 as described in @rweb{Bug reports}.
  97
  98 @warning{
  99 The automatic comparison of the regtests checks the
 100 LilyPond bounding boxes and the log files.  This means that
 101 Ghostscript changes and changes in
 102 lyrics or text are not found.  However, errors and warnings that
 103 are printed to the log file but
 104 do not change the graphical layout are also identified.
 105
 106 Periodic manual checking of the
 107 complete regtest output should be performed to catch anything
 108 missed by the automatic comparison.}
 109
 110 @node Compiling regression tests
 111 @section Compiling regression tests
 112
 113 Developers may wish to see the output of the complete regression
 114 test suite for the current version of the source repository
 115 between releases.  Current source code is available; see
 116 @ref{Working with source code}.  Then you will need
 117 to build the LilyPond binary; see @ref{Compiling LilyPond}.
 118
 119 Uninstalling the previous LilyPond version is not necessary, nor is
 120 running @code{make install}, since the tests will automatically be
 121 compiled with the LilyPond binary you have just built in your source
 122 directory.
 123
 124 From this point, the regtests are compiled with:
 125
 126 @example
 127 make test
 128 @end example
 129
 130 If you have a multi-core machine you may want to use the @option{-j}
 131 option and @var{CPU_COUT} variable, as
 132 described in @ref{Saving time with CPU_COUNT}.
 133 For a quad-core processor the complete command would be:
 134
 135 @example
 136 make -j5 CPU_COUNT=5 test
 137 @end example
 138
 139 The regtest output will then be available in
 140 @file{input/regression/out-test}.
 141 @file{input/regression/out-test/collated-examples.html}
 142 contains a listing of all the regression tests that were run,
 143 but none of the images are included.  Individual images are
 144 also available in this directory.
 145
 146 The primary use of @samp{make@tie{}test} is to verify that the
 147 regression tests all run without error.  The regression test
 148 page that is part of the documentation is created only when the
 149 documentation is built, as described in @ref{Generating documentation}.
 150 Note that building the documentation requires more installed components
 151 than building the source code, as described in
 152 @ref{Requirements for building documentation}.
 153
 154
 155 @node Identifying code regressions
 156 @section Identifying code regressions
 157
 158 Before modified code is committed to master, a regression test
 159 comparision must be completed to ensure that the changes have
 160 not caused problems with previously working code.  The comparison
 161 is made automatically upon compiling the regression test suite
 162 twice.
 163
 164 Before making changes, a baseline should be established by running:
 165
 166 @example
 167 make test-baseline
 168 @end example
 169
 170 After making the changes, the code should be checked by running:
 171
 172 @example
 173 make check
 174 @end example
 175
 176 After @samp{make@tie{}check} is complete, a regression test comparison
 177 will be available at @file{out/test-results/index.html}.
 178 For each regression test that differs between the baseline and the
 179 changed code, a regression test entry will displayed.  Ideally, the
 180 only changes would be the changes that you were working on.  If
 181 regressions are introduced, they must be fixed before committing the
 182 code.
 183
 184 @warning{
 185 The special regression test @file{test-output-distance.ly} will always
 186 show up as a regression.  This test changes each time it is run, and
 187 serves to verify that the regression tests have, in fact, run.}
 188
 189 @node Memory and coverage tests
 190 @section Memory and coverage tests
 191
 192 In addition to the graphical output of the regression tests, it is
 193 possible to test memory usage and to determine how much of the source
 194 code has been exercised by the tests.
 195
 196 @subheading Memory usage
 197
 198 For tracking memory usage as part of this test, you will need
 199 GUILE CVS; especially the following patch:
 200 @uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
 201
 202 @subheading Code coverage
 203
 204 For checking the coverage of the test suite, do the following
 205
 206 @example
 207 ./scripts/auxiliar/build-coverage.sh
 208 @emph{# uncovered files, least covered first}
 209 ./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
 210 @emph{# consecutive uncovered lines, longest first}
 211 ./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
 212 @end example
 213
 214
 215 @node MusicXML tests
 216 @section MusicXML tests
 217
 218
 219 LilyPond comes with a complete set of regtests for the
 220 @uref{http://www.musicxml.org/,MusicXML} language.  Originally
 221 developed to test @samp{musicxml2ly}, these regression tests
 222 can be used to test any MusicXML implementation.
 223
 224 The MusicXML regression tests are found at
 225 @file{input/regression/musicxml/}.
 226
 227 The output resulting from running these tests
 228 through @samp{muscxml2ly} followed by @samp{lilypond} is
 229 available in the LilyPond documentation:
 230
 231 @example
 232 @uref{http://lilypond.org/doc/latest/input/regression/musicxml/collated-files}
 233 @end example
 234