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