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 * Current regtest output::
   8 * Comparison regtest output::
   9 * MusicXML tests::
  10 @end menu
  11
  12
  13 @node Introduction to regression tests
  14 @section Introduction to regression tests
  15
  16 LilyPond has a complete suite of regression tests that are used
  17 to ensure that changes to the code do not break existing behavior.
  18 These regression tests comprise small LilyPond snippets that test
  19 the functionality of each part of LilyPond.
  20
  21 Regression tests are added when new functionality is added to
  22 LilyPond.  They are also added when bugs are identified.  The
  23 snippet that causes the bug becomes a regression test to verify
  24 that the bug has been fixed.
  25
  26 The regression tests are automatically compiled using special @code{make}
  27 targets.  The output of the regression tests is also automatically
  28 checked to identify changes in LilyPond output.
  29
  30 The output of the regression tests is available on the website
  31 for every stable version of LilyPond.  This allows the comparison
  32 of different versions to see when bugs appeared.
  33
  34
  35 @node Current regtest output
  36 @section Current regtest output
  37
  38
  39 TODO: To be checked and completed -vv
  40
  41 Regression tests (@qq{regtests}) are available in two ways: either
  42 in a compiled form, for instance on the website, or as source code
  43 that needs to be compiled locally, using the most recent LilyPond
  44 binary as possible.  The latter is recommended, although more
  45 technically involved.
  46
  47
  48 @subheading Precompiled regtests
  49
  50 The easiest way to see the @q{current} regtest output (meaning,
  51 the ouput of the latest stable or development version) is
  52 to look at the online compiled regtest page:
  53
  54 @example
  55 @uref{http://lilypond.org/doc/latest/input/regression/collated-files.html}
  56 @end example
  57
  58 However, depending on how many changes have been made to the code
  59 since the latest release, this page may not reflect the latest
  60 features, bugfixes... or new bugs that may have been introduced!
  61
  62 Therefore, if you have an appropriate environment to build LilyPond
  63 yourself, it is recommended that you compile the software yourself.
  64
  65
  66 @subheading Compiling regtests
  67
  68 The first step is to download the latest available source code,
  69 as explained in @ref{Working with source code}.  Then you will need
  70 to build the LilyPond binary: see
  71 @ref{Compiling LilyPond}.
  72
  73 @noindent
  74 (Uninstalling the previous LilyPond version is not necessary, nor is
  75 running @code{make install}, since the tests will automatically be
  76 compiled with the LilyPond binary you have just built in your source
  77 directory.)
  78
  79 From this point, compiling the regtests is as simple as running
  80
  81 @example
  82 make test
  83 @end example
  84
  85 However, as there are many snippets to compile, if you have a multi-core
  86 machine it is highly recommended to use the @option{-j} option, as
  87 described in @ref{Saving time with the @option{-j} option}.  Another
  88 useful optimization is to set the @var{CPU_COUNT} variable; for a
  89 quad-core processor the complete command would look like
  90
  91 @example
  92 make -j5 CPU_COUNT=4 test
  93 @end example
  94
  95 The regtest output will then be available in one of the
  96 @file{input/regression/out-*} directories, depending on the
  97 exact command you used.  See @ref{Testing LilyPond} for
  98 more information.
  99
 100
 101 @node Comparison regtest output
 102 @section Comparison regtest output
 103
 104
 105 Regtests are an useful way to compare what has changed between two
 106 versions of LilyPond, or to verify on a fine-grained level if a
 107 particular change may have unwanted side-effects, such as introducing
 108 a bug or breaking existing features.
 109
 110 For such cases, LilyPond's build system provides an automated way of
 111 comparing regtests output.
 112
 113
 114 @subheading Comparing regtests for two development releases
 115
 116 Each time a new development version is released, a set of regtests is
 117 compiled and compared with the previous release.  The result of these
 118 comparisons is archived online, and may be seen at the following address:
 119
 120 @example
 121 @uref{http://lilypond.org/test/}
 122 @end example
 123
 124 @noindent
 125 Checking these pages is a very important task for the LilyPond project.
 126 You are invited to report anything that looks broken, or any case
 127 where the output quality is not on par with the previous release,
 128 either to the Bug Squad, following our guidelines for
 129 @rweb{Bug reports}, or directly in the bug tracker, as explained in
 130 @ref{Issues}.
 131
 132
 133 @subheading Comparing regtests when modifying the source code
 134
 135 When changing any piece of code, developers are asked to verify that the
 136 regtests still compile successfuly (i.e., not only without error, but
 137 with an output quality equivalent or superior).  This may be done as
 138 described in @ref{Testing LilyPond}.
 139
 140
 141 @node MusicXML tests
 142 @section MusicXML tests
 143
 144
 145 LilyPond comes with a fairly complete set of regtests for the
 146 @uref{http://www.musicxml.org/,MusicXML} language.  These tests may
 147 be seen online at the following address:
 148
 149 @example
 150 @uref{http://lilypond.org/doc/latest/input/regression/musicxml/collated-files}
 151 @end example
 152
 153 TBC
 154