
The quvi test suite [IFHD]

Requires:
    * Perl (and prove <http://search.cpan.org/perldoc?prove>)
    * Perl modules (that are not among the 5.12.2 core modules)
        - Test::Deep <http://search.cpan.org/perldoc/Test::Deep>
        - JSON::XS <http://search.cpan.org/perldoc?JSON::XS>

Notes:
    * Running "make check" can be a lengthy process
        - The tests are disabled by default
        - Run configure with --enable-tests to enable them

    * Most of the tests require an Internet connection
        - The required bandwidth varies, e.g.
            - The fetched video pages can be anything from ~5KB to ~100KB
            - The fetched configs and playlists are often much smaller

    * You may run individual tests manually (e.g. outside of "make check"),
      in which case you need to specify the path to the quvi(1) command
      (unless it's found in your $PATH)
        -  Depending on your setup you may also need to specify the
           path to the quvi LUA scripts (see $top_srcdir/share/)
           if the quvi(1) command cannot find them itself (see also
           "Arguments to tests" further below)

    * quvi picks whatever settings you may have have in ~/.quvirc
        - Keep this in mind when you run the tests

    * You can use the script(1) command to log the tests, e.g.:
        % script -c "make check" foo.log

Run: Tests ($top_srcdir/tests/t/*.t)

    % cd $top_srcdir ; mkdir tmp ; cd tmp ;
    % ../configure --enable-tests && make check (or "make test")

    Similar, but without "make check":

    (assuming you have build quvi in $top_srcdir/tmp)
    % cd $top_srcdir/tests
    % prove -l t/ :: -q ../tmp/src/quvi -b ../share

    You can also choose which of the tests to run by specifying them in
    the command line, e.g.:
        % prove -l t/nosupport.t :: -q ../tmp/src/quvi -b ../share

    See also the prove manual. Use script(1) or something similar if you
    need to produce log the output.

Run: Tests ($top_srcdir/tests/t/d/*.t) -- Note the 'd'

    These tests are *not* run by "make check". You may find these tests
    useful when you are working on a new website script.

    (assuming you have build quvi in $top_srcdir/tmp and the LUA
    scripts reside in $top_srcdir/share/)
    % cd $top_srcdir/tests
    % prove -l t/d/url.t :: -q ../tmp/src/quvi -b ../share \
        -u $test_url

    Or, if you have been following the steps in HowtoWriteWebsiteScript
    ("2.3.2. Working with precompiled binaries"), you could do the
    following:

    % cd foo
    % cp -r $top_srcdir/tests/lib/ .
    % mkdir t ; cp $top_srcdir/tests/t/d/url.t t/
    % prove -l :: -u $test_url

    # Same but check against a JSON.
    % quvi -q $test_url > foo.json
    % prove -l :: -u $test_url -j foo.json

    See also the prove manual. Use script(1) or something similar if you
    need to produce log the output.

Arguments to tests

    (quote from prove manual)
    "It is possible to supply arguments to tests. To do so separate
    them from prove's own arguments with the arisdottle, '::'.
    For example:
        prove -v t/mytest.t :: --url http://example.com

    would run t/mytest.t with the options '--url http://example.com'.
    When running multiple tests they will each receive the same
    arguments."
    (eoq)

    With this in mind, Test::Quvi supports the following args:
        -q,--quvi-path arg      Path to quvi(1) command
        -b,--quvi-basedir arg   Path to dir containing the (quvi) LUA scripts
        -o,--quvi-opts arg      Additional options to quvi(1) command
        -j,--json-file arg      Verify received data against local JSON file
        -J,--dump-json          Print quvi generated JSON to stderr
        -i,--ignore arg         Ignore arg in JSON comparison
        -d,--data-root arg      Path to directory containing the (test) data/
        -v,--valgrind-path arg  Path to valgrind(1) command

    The test suite presumes that quvi is found in the $PATH, unless
    --quvi-path is specified.

    If quvi cannot find the LUA scripts, use the --quvi-basedir option,
    e.g. -b $top_srcdir/share/.

    You can pass additional options to quvi, e.g:
        % prove t/foo.t :: -o "-qs"

    The test suite can check the returned against JSONs. Use the
    --json-file if you need to do this.

    Note about the t/d/url.t:  you can tell the test to use the
    (page) URL from the JSON instead of specifying it in the command
    line with --url.

    Use the --ignore option if you need to ignore any of the JSON
    values. e.g.:
        % prove t/foo.t :: -i content_type
    or
        % prove t/foo.t :: -i content_type,page_title,host

    Use comma (,) to separate each field name that should be ignored.

    NOTE: The test suite ignores some of the values (e.g. media URL,
    thumbnail URL) by default.

Data: JSON

    The JSON data exist for confirming that quvi returns the expected
    results. See the $top_srcdir/tests/data/ directory.

     $top_srcdir/tests/data/resolve/
        Resolve shortened, redirect etc. For example, shortened.t and
        redirect.t use these JSONs.

     $top_srcdir/tests/data/format/default/
        JSONs produced by either "quvi $test_url" or "quvi $test_url -f
        default". Each website should have at least one of these.

     $top_srcdir/tests/data/format/default/nsfw/
        Data for NSFW scripts. Ignored unless configure is run with the
        --enable-nsfw switch.

     $top_srcdir/tests/data/format/default/ignore/
        Read the README in this directory.

     $top_srcdir/tests/data/format/default/non-http/
        Read the README in this directory.

     $top_srcdir/tests/data/format/other/
        JSONs for those websites that support more than just the
        'default format'. One JSON for each format.

     $top_srcdir/tests/data/format/other/ignore/
        Read the README in this directory.
