tests/README

   1
   2 quvi test suite
   3 ===============
   4
   5 Prerequisites
   6 -------------
   7
   8   * quvi 0.4.1+
   9      - The test suite uses the new options introduced in quvi 0.4.1,
  10        e.g. "-vq" instead of (now depr.) "-q", etc.
  11
  12   * Perl (and prove <http://search.cpan.org/perldoc?prove>)
  13
  14   * Perl modules (that are not among the 5.12.2 core modules)
  15      - Test::Deep <http://search.cpan.org/perldoc/Test::Deep>
  16      - JSON::XS <http://search.cpan.org/perldoc?JSON::XS>
  17
  18 Notes
  19 -----
  20
  21   * Running "make check" can be a lengthy process
  22     - The tests are disabled by default
  23     - Run configure with --with-tests to enable them
  24     - The tests require an internet connection
  25
  26   * To run individual tests, run prove with the -q and -b options,
  27     see examples below
  28
  29   * quvi command reads the ~/.quvirc, keep this in mind when
  30     you use the test suite
  31
  32   * If you report bugs detected by the test suite, please send the log
  33     (omit whatever is irrelevant to prevent clutter):
  34
  35       script -c "make check" foo.log
  36
  37 Running
  38 -------
  39
  40   cd $top_srcdir ; mkdir tmp ; cd tmp ;
  41   ../configure --with-tests && make check (or "make test")
  42
  43 Similar, but without "make check":
  44
  45   (assuming you have build quvi in $top_srcdir/tmp)
  46   cd $top_srcdir/tests
  47   prove -l t/ :: -q path/to/quvi/command -b ../share
  48
  49 Running: Individual tests
  50 -------------------------
  51
  52   prove -l t/nosupport.t :: -q /path/to/quvi/command -b ../share
  53
  54 Running: Custom tests
  55 ---------------------
  56
  57 See the $top_srcdir/tests/t/d/ directory. These tests are not run by the
  58 test suite when you type "make check". You may find these tests useful
  59 when you are, for example, developing a new webscript.
  60
  61   (assuming you have build quvi in $top_srcdir/tmp and the lua
  62   scripts reside in $top_srcdir/share/)
  63   cd $top_srcdir/tests
  64   prove -l t/d/url.t :: -q /path/to/quvi/command -b ../share \
  65         -u $test_url
  66
  67 Arguments to tests
  68 ------------------
  69
  70 "It is possible to supply arguments to tests. To do so separate
  71 them from prove's own arguments with the arisdottle, '::'.
  72 For example:
  73
  74   prove -v t/mytest.t :: --url http://example.com
  75
  76 would run t/mytest.t with the options '--url http://example.com'.
  77 When running multiple tests they will each receive the same
  78 arguments." -- prove(1)
  79
  80 The test suite supports the following options:
  81
  82   -q,--quvi-path arg            Path to quvi(1) command
  83   -b,--libquvi-scriptsdir arg   Path to dir containing the libquvi-scripts
  84   -o,--quvi-opts arg            Additional options to quvi(1) command
  85   -j,--json-file arg            Verify received data against local JSON file
  86   -J,--dump-json                Print quvi generated JSON to stderr
  87   -i,--ignore arg               Ignore arg in JSON comparison
  88   -d,--data-root arg            Path to directory containing the (test) data/
  89   -v,--valgrind-path arg        Path to valgrind(1) command
  90
  91 Note that the test suite presumes that quvi command is either found in
  92 the $PATH or -q is used to define the path to the command.
  93
  94 If quvi cannot find the lua scripts, use the --libquvi-scriptsdir option,
  95 e.g. "-b $top_srcdir/share/"
  96
  97 You can pass additional options to quvi, e.g:
  98
  99   prove t/foo.t :: -o "-vq -e-r"
 100
 101 The test suite uses the bundled JSON files for the verification process.
 102 You have the option of using --json-file with the "Custom tests" (see
 103 above), e.g.:
 104
 105   prove -l t/d/url.t :: \
 106     -q /path/to/quvi/command -b ../share \
 107     -j data/format/default/youtube.json
 108
 109 Use the --ignore option if you need to ignore any of the values in the
 110 JSON, e.g.:
 111
 112   prove t/foo.t :: -i content_type
 113 Or
 114   prove t/foo.t :: -i content_type,page_title,host
 115
 116 The test suite ignores some of the values (e.g. media URL,
 117 thumbnail URL) by default.
 118
 119 Environment
 120 -----------
 121
 122 Set TEST_VERBOSE to amp up the verbosity level of the tests. If you
 123 run the tests manually with prove(1), use -v with prove command
 124 instead. TEST_VERBOSE is only picked by the "make check".
 125
 126 Set TEST_SKIP if you'd like to skip any of the test groups, e.g.:
 127
 128   export TEST_SKIP=mem,format_default
 129
 130 You can run the "find-tests.sh" script found in the top source directory
 131 to get a list of the test names that can be used with TEST_SKIP.
 132
 133 Test suite data
 134 ---------------
 135
 136 The $top_srcdir/data/ contains the JSON files that the test suite uses.
 137
 138   $top_srcdir/tests/data/resolve/
 139
 140     Resolve shortened, redirect etc. For example, shortened.t and
 141     redirect.t use these JSONs.
 142
 143   $top_srcdir/tests/data/format/default/
 144
 145     JSONs produced by either "quvi $test_url" or "quvi $test_url -f
 146     default". Each website should have at least one of these.
 147
 148   $top_srcdir/tests/data/format/default/nsfw/
 149
 150     Data for NSFW scripts. Ignored unless configure is run with the
 151     --with-nsfw switch.
 152
 153   $top_srcdir/tests/data/format/default/ignore/
 154
 155     Read the README in this directory.
 156
 157   $top_srcdir/tests/data/format/other/
 158
 159     JSONs for those websites that support more than just the
 160     'default format'. One JSON for each format.
 161
 162   $top_srcdir/tests/data/format/other/ignore/
 163
 164     Read the README in this directory.