tests/README

   1
   2 The quvi test suite [IFHD]
   3
   4 Requires:
   5     * Perl (and prove <http://search.cpan.org/perldoc?prove>)
   6     * Perl modules (that are not among the 5.12.2 core modules)
   7         - Test::Deep <http://search.cpan.org/perldoc/Test::Deep>
   8         - JSON::XS <http://search.cpan.org/perldoc?JSON::XS>
   9
  10 Notes:
  11     * Running "make check" can be a lengthy process
  12         - The tests are disabled by default
  13         - Run configure with --enable-tests to enable them
  14
  15     * Most of the tests require an Internet connection
  16         - The required bandwidth varies, e.g.
  17             - The fetched video pages can be anything from ~5KB to ~100KB
  18             - The fetched configs and playlists are often much smaller
  19
  20     * You may run individual tests manually (e.g. outside of "make check"),
  21       in which case you need to specify the path to the quvi(1) command
  22       (unless it's found in your $PATH)
  23         -  Depending on your setup you may also need to specify the
  24            path to the quvi LUA scripts (see $top_srcdir/share/)
  25            if the quvi(1) command cannot find them itself (see also
  26            "Arguments to tests" further below)
  27
  28     * quvi picks whatever settings you may have have in ~/.quvirc
  29         - Keep this in mind when you run the tests
  30
  31     * You can use the script(1) command to log the tests, e.g.:
  32         % script -c "make check" foo.log
  33
  34 Run: Tests ($top_srcdir/tests/t/*.t)
  35
  36     % cd $top_srcdir ; mkdir tmp ; cd tmp ;
  37     % ../configure --enable-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 ../tmp/src/quvi/quvi -b ../share
  44
  45     You can also choose which of the tests to run by specifying them in
  46     the command line, e.g.:
  47         % prove -l t/nosupport.t :: -q ../tmp/src/quvi/quvi -b ../share
  48
  49     See also the prove manual. Use script(1) or something similar if you
  50     need to produce log the output.
  51
  52 Run: Tests ($top_srcdir/tests/t/d/*.t) -- Note the 'd'
  53
  54     These tests are *not* run by "make check". You may find these tests
  55     useful when you are working on a new website script.
  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 ../tmp/src/quvi/quvi -b ../share \
  61         -u $test_url
  62
  63     Or, if you have been following the steps in HowtoWriteWebsiteScript
  64     ("2.3.2. Working with precompiled binaries"), you could do the
  65     following:
  66
  67     % cd foo
  68     % cp -r $top_srcdir/tests/lib/ .
  69     % mkdir t ; cp $top_srcdir/tests/t/d/url.t t/
  70     % prove -l :: -u $test_url
  71
  72     # Same but check against a JSON.
  73     % quvi -q $test_url > foo.json
  74     % prove -l :: -u $test_url -j foo.json
  75
  76     See also the prove manual. Use script(1) or something similar if you
  77     need to produce log the output.
  78
  79 Arguments to tests
  80
  81     (quote from prove manual)
  82     "It is possible to supply arguments to tests. To do so separate
  83     them from prove's own arguments with the arisdottle, '::'.
  84     For example:
  85         prove -v t/mytest.t :: --url http://example.com
  86
  87     would run t/mytest.t with the options '--url http://example.com'.
  88     When running multiple tests they will each receive the same
  89     arguments."
  90     (eoq)
  91
  92     With this in mind, Test::Quvi supports the following args:
  93         -q,--quvi-path arg      Path to quvi(1) command
  94         -b,--quvi-basedir arg   Path to dir containing the (quvi) LUA scripts
  95         -o,--quvi-opts arg      Additional options to quvi(1) command
  96         -j,--json-file arg      Verify received data against local JSON file
  97         -J,--dump-json          Print quvi generated JSON to stderr
  98         -i,--ignore arg         Ignore arg in JSON comparison
  99         -d,--data-root arg      Path to directory containing the (test) data/
 100         -v,--valgrind-path arg  Path to valgrind(1) command
 101
 102     The test suite presumes that quvi is found in the $PATH, unless
 103     --quvi-path is specified.
 104
 105     If quvi cannot find the LUA scripts, use the --quvi-basedir option,
 106     e.g. -b $top_srcdir/share/.
 107
 108     You can pass additional options to quvi, e.g:
 109         % prove t/foo.t :: -o "-qr"
 110
 111     The test suite can check the returned against JSONs. Use the
 112     --json-file if you need to do this.
 113
 114     Tip: url.t can read page URL from the JSON with -j
 115     For example:
 116         prove -l t/d/url.t :: \
 117             -q ../tmp/src/quvi/quvi -b ../share \
 118             -j data/format/default/youtube.json
 119
 120     Use the --ignore option if you need to ignore any of the JSON
 121     values. e.g.:
 122         % prove t/foo.t :: -i content_type
 123     or
 124         % prove t/foo.t :: -i content_type,page_title,host
 125
 126     Use comma (,) to separate each field name that should be ignored.
 127
 128     NOTE: The test suite ignores some of the values (e.g. media URL,
 129     thumbnail URL) by default.
 130
 131 Environment:
 132
 133     Set TEST_VERBOSE to amp up the verbosity level of the tests. If you
 134     run the tests manually with prove(1), use -v with prove command
 135     instead. TEST_VERBOSE is only picked by the "make check".
 136
 137 Data: JSON
 138
 139     The JSON data exist for confirming that quvi returns the expected
 140     results. See the $top_srcdir/tests/data/ directory.
 141
 142      $top_srcdir/tests/data/resolve/
 143         Resolve shortened, redirect etc. For example, shortened.t and
 144         redirect.t use these JSONs.
 145
 146      $top_srcdir/tests/data/format/default/
 147         JSONs produced by either "quvi $test_url" or "quvi $test_url -f
 148         default". Each website should have at least one of these.
 149
 150      $top_srcdir/tests/data/format/default/nsfw/
 151         Data for NSFW scripts. Ignored unless configure is run with the
 152         --enable-nsfw switch.
 153
 154      $top_srcdir/tests/data/format/default/ignore/
 155         Read the README in this directory.
 156
 157      $top_srcdir/tests/data/format/default/non-http/
 158         Read the README in this directory.
 159
 160      $top_srcdir/tests/data/format/other/
 161         JSONs for those websites that support more than just the
 162         'default format'. One JSON for each format.
 163
 164      $top_srcdir/tests/data/format/other/ignore/
 165         Read the README in this directory.