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 -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 -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 -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     Note about the t/d/url.t:  you can tell the test to use the
 115     (page) URL from the JSON instead of specifying it in the command
 116     line with --url.
 117
 118     Use the --ignore option if you need to ignore any of the JSON
 119     values. e.g.:
 120         % prove t/foo.t :: -i content_type
 121     or
 122         % prove t/foo.t :: -i content_type,page_title,host
 123
 124     Use comma (,) to separate each field name that should be ignored.
 125
 126     NOTE: The test suite ignores some of the values (e.g. media URL,
 127     thumbnail URL) by default.
 128
 129 Data: JSON
 130
 131     The JSON data exist for confirming that quvi returns the expected
 132     results. See the $top_srcdir/tests/data/ directory.
 133
 134      $top_srcdir/tests/data/resolve/
 135         Resolve shortened, redirect etc. For example, shortened.t and
 136         redirect.t use these JSONs.
 137
 138      $top_srcdir/tests/data/format/default/
 139         JSONs produced by either "quvi $test_url" or "quvi $test_url -f
 140         default". Each website should have at least one of these.
 141
 142      $top_srcdir/tests/data/format/default/nsfw/
 143         Data for NSFW scripts. Ignored unless configure is run with the
 144         --enable-nsfw switch.
 145
 146      $top_srcdir/tests/data/format/default/ignore/
 147         Read the README in this directory.
 148
 149      $top_srcdir/tests/data/format/default/non-http/
 150         Read the README in this directory.
 151
 152      $top_srcdir/tests/data/format/other/
 153         JSONs for those websites that support more than just the
 154         'default format'. One JSON for each format.
 155
 156      $top_srcdir/tests/data/format/other/ignore/
 157         Read the README in this directory.