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 The easiest way to see the @q{current} regtest output (meaning,
  42 the ouput of the latest stable or development version) is
  43 to look at the precompiled regtest
  44 @uref{../../input/regression/collated-files.html, HTML page} or its
  45 @uref{../../input/regression/collated-files.pdf, pdf version}.
  46
  47 However, depending on how many changes have been made to the code
  48 since the latest release, this page may not reflect the latest
  49 features, bugfixes... or new bugs that may have been introduced!
  50
  51 Therefore, if you have an appropriate environment to build LilyPond
  52 yourself, it is recommended that you compile the software yourself.
  53
  54 The first step is to download the latest available source code,
  55 as explained in @ref{Working with source code}.  Then you will need
  56 to build the LilyPond binary@footnote{Uninstalling the previous
  57 LilyPond version is not necessary, nor is running @code{make install},
  58 since the tests will automatically be compiled with the LilyPond binary
  59 you have just built in your source directory.}: see
  60 @rcontrib{Compiling LilyPond}.
  61
  62 From this point, compiling the regtests is as simple as running
  63
  64 @example
  65   make test
  66 @end example
  67
  68 However, as there are many snippets to compile, if you have a multi-core
  69 machine it is highly recommended to use the @option{-j} option, as
  70 described in @ref{Saving time with the @option{-j} option}.  Another
  71 useful optimization is to set the @var{CPU_COUNT} variable; for a
  72 quad-core processor the complete command would look like
  73
  74 @example
  75   make -j5 CPU_COUNT=4 test
  76 @end example
  77
  78 The regtest output will then be available in one of the
  79 @file{input/regression/out-*} directories, depending on the
  80 exact command you used.
  81
  82
  83 @node Comparison regtest output
  84 @section Comparison regtest output
  85
  86
  87 @node MusicXML tests
  88 @section MusicXML tests
  89
  90