git.sesse.net Git - ffmpeg/blob - doc/fate.texi

   1 \input texinfo @c -*- texinfo -*-
   2
   3 @settitle FATE Automated Testing Environment
   4 @titlepage
   5 @center @titlefont{FATE Automated Testing Environment}
   6 @end titlepage
   7
   8 @top
   9
  10 @contents
  11
  12 @chapter Introduction
  13
  14 FATE provides a regression testsuite embedded within the Libav build system.
  15 It can be run locally and optionally configured to send reports to a web
  16 aggregator and viewer @url{http://fate.libav.org}.
  17
  18 It is advised to run FATE before submitting patches to the current codebase
  19 and provide new tests when submitting patches to add additional features.
  20
  21 @chapter Running FATE
  22
  23 @section Samples and References
  24 In order to run, FATE needs a large amount of data (samples and references)
  25 that is provided separately from the actual source distribution.
  26
  27 To inform the build system about the testsuite location, pass
  28 @option{--samples=<path to the samples>} to @command{configure} or set the
  29 @var{SAMPLES} Make variable or the @var{LIBAV_SAMPLES} environment variable
  30 to a suitable value.
  31
  32 To use a custom wrapper to run the test, pass @option{--target-exec} to
  33 @command{configure} or set the @var{TARGET_EXEC} Make variable.
  34
  35 The dataset is available through @command{rsync}, is possible to fetch
  36 the current sample using the straight rsync command or through a specific
  37 @ref{Makefile target}.
  38
  39 @example
  40 # rsync -aL rsync://fate-suite.libav.org/fate-suite/ fate-suite
  41 @end example
  42
  43 @example
  44 # make fate-rsync SAMPLES=fate-suite
  45 @end example
  46
  47
  48 @chapter Manual Run
  49 FATE regression test can be run through @command{make}.
  50 Specific Makefile targets and Makefile variables are available:
  51
  52 @anchor{Makefile target}
  53 @section FATE Makefile targets
  54
  55 @table @option
  56 @item fate-list
  57 List all fate/regression test targets.
  58
  59 @item fate-rsync
  60 Shortcut to download the fate test samples to the specified testsuite location.
  61
  62 @item fate
  63 Run the FATE test suite (requires the fate-suite dataset).
  64 @end table
  65
  66 @section FATE Makefile variables
  67 @table @option
  68 @item V
  69 Verbosity level, can be set to 0, 1 or 2.
  70
  71 @table @option
  72 @item 0
  73 show just the test arguments
  74
  75 @item 1
  76 show just the command used in the test
  77
  78 @item 2
  79 show everything
  80 @end table
  81
  82 @item SAMPLES
  83 Specify or override the path to the FATE samples at make time, it has a
  84 meaning only while running the regression tests.
  85
  86 @item THREADS
  87 Specify how many threads to use while running regression tests, it is
  88 quite useful to detect thread-related regressions.
  89
  90 @item THREAD_TYPE
  91 Specify which threading strategy test, either @var{slice} or @var{frame},
  92 by default @var{slice+frame}
  93
  94 @item CPUFLAGS
  95 Specify a mask to be applied to autodetected CPU flags.
  96
  97 @item TARGET_EXEC
  98 Specify or override the wrapper used to run the tests.
  99
 100 @item GEN
 101 Set to @var{1} to generate the missing or mismatched references.
 102 @end table
 103
 104 @example
 105     make V=1 SAMPLES=/var/fate/samples THREADS=2 CPUFLAGS=mmx fate
 106 @end example
 107
 108 @chapter Automated Tests
 109 In order to automatically testing specific configurations, e.g. multiple
 110 compilers, @command{tests/fate.sh} is provided.
 111
 112 This shell script builds Libav, runs the regression tests and prepares
 113 a report that can be sent to @url{http://fate.libav.org/} or directly
 114 examined locally.
 115
 116 @section Testing Profiles
 117 The configuration file passed to @command{fate.sh} is shell scripts as well.
 118
 119 It must provide at least a @var{slot} identifier, the @var{repo} from
 120 which fetch the sources, the @var{samples} directory, a @var{workdir} with
 121 enough space to build and run all the tests.
 122 Optional submit command @var{fate_recv} and a @var{comment} to describe
 123 the testing profile are available.
 124
 125 Additional optional parameter to tune the Libav building and reporting process
 126 can be passed.
 127
 128 @example
 129 slot=                                   # some unique identifier
 130 repo=git://git.libav.org/libav.git      # the source repository
 131 #branch=release/10                      # the branch to test
 132 samples=/path/to/fate/samples
 133 workdir=                                # directory in which to do all the work
 134 fate_recv="ssh -T fate@@fate.libav.org"  # command to submit report
 135 comment=                                # optional description
 136 build_only=     # set to "yes" for a compile-only instance that skips tests
 137
 138 # the following are optional and map to configure options
 139 arch=
 140 cpu=
 141 cross_prefix=
 142 as=
 143 cc=
 144 ld=
 145 target_os=
 146 sysroot=
 147 target_exec=
 148 target_path=
 149 target_samples=
 150 extra_cflags=
 151 extra_ldflags=
 152 extra_libs=
 153 extra_conf=     # extra configure options not covered above
 154
 155 #make=          # name of GNU make if not 'make'
 156 makeopts=       # extra options passed to 'make'
 157 #tar=           # command to create a tar archive from its arguments on
 158                 # stdout, defaults to 'tar c'
 159 @end example
 160
 161 @section Special Instances
 162 The @var{TARGET_EXEC} option provides a way to run FATE wrapped in
 163 @command{valgrind}, @command{qemu-user} or @command{wine} or on remote targets
 164 through @command{ssh}.
 165
 166 @section Submitting Reports
 167 In order to send reports you need to create an @command{ssh} key and send it
 168 to @email{root@@libav.org}.