tests/README

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