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 test suite 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 test suite 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 test suite 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
 103 @item HWACCEL
 104 Specify which hardware acceleration to use while running regression tests,
 105 by default none is used.
 106
 107 @end table
 108
 109 @example
 110     make V=1 SAMPLES=/var/fate/samples THREADS=2 CPUFLAGS=mmx fate
 111 @end example
 112
 113 @chapter Automated Tests
 114 In order to automatically testing specific configurations, e.g. multiple
 115 compilers, @command{tests/fate.sh} is provided.
 116
 117 This shell script builds Libav, runs the regression tests and prepares
 118 a report that can be sent to @url{http://fate.libav.org/} or directly
 119 examined locally.
 120
 121 @section Testing Profiles
 122 The configuration file passed to @command{fate.sh} is shell scripts as well.
 123
 124 It must provide at least a @var{slot} identifier, the @var{repo} from
 125 which fetch the sources, the @var{samples} directory, a @var{workdir} with
 126 enough space to build and run all the tests.
 127 Optional submit command @var{fate_recv} and a @var{comment} to describe
 128 the testing profile are available.
 129
 130 Additional optional parameter to tune the Libav building and reporting process
 131 can be passed.
 132
 133 @example
 134 slot=                                   # some unique identifier
 135 repo=git://git.libav.org/libav.git      # the source repository
 136 #branch=release/10                      # the branch to test
 137 samples=/path/to/fate/samples
 138 workdir=                                # directory in which to do all the work
 139 fate_recv="ssh -T fate@@fate.libav.org"  # command to submit report
 140 comment=                                # optional description
 141 build_only=     # set to "yes" for a compile-only instance that skips tests
 142 ignore_tests=
 143
 144 # the following are optional and map to configure options
 145 arch=
 146 cpu=
 147 cross_prefix=
 148 as=
 149 cc=
 150 ld=
 151 target_os=
 152 sysroot=
 153 target_exec=
 154 target_path=
 155 target_samples=
 156 extra_cflags=
 157 extra_ldflags=
 158 extra_libs=
 159 extra_conf=     # extra configure options not covered above
 160
 161 #make=          # name of GNU make if not 'make'
 162 makeopts=       # extra options passed to 'make'
 163 #makeopts_fate= # extra options passed to 'make' when running tests,
 164                 # defaulting to makeopts above if this is not set
 165 #tar=           # command to create a tar archive from its arguments on
 166                 # stdout, defaults to 'tar c'
 167 @end example
 168
 169 @section Special Instances
 170 The @var{TARGET_EXEC} option provides a way to run FATE wrapped in
 171 @command{valgrind}, @command{qemu-user} or @command{wine} or on remote targets
 172 through @command{ssh}.
 173
 174 @section Submitting Reports
 175 In order to send reports you need to create an @command{ssh} key and send it
 176 to @email{root@@libav.org}.