WWW::Search::Test - phpMan

NAME
    WWW::Search::Test - utilities to aid in testing WWW::Search backends

SYNOPSIS
      $oTest = new WWW::Search::Test('HotBot,Yahoo,Excite');
      $oTest->test('HotBot', 'Kingpin', 'one', $sQuery, $TEST_RANGE, 1, 10);

DESCRIPTION
    See file test.pl in the WWW-Search-HotBot distribution for a detailed
    "real-world" example.

METHODS AND FUNCTIONS
  find_websearch
    Returns the full path of an executable WebSearch program, or undef if
    none can be found.

  new
    Create a new WWW::Search::Test object. All arguments are strings, names
    of backends that this object will be able to test. If no arguments are
    given, will be able to test all backends.

  mode
    Set / get the test mode of this object. If an argument is given, sets
    the mode to that value. Returns the current (or newly set) value.

    There are three test modes available. They are:

      $MODE_INTERNAL: parse URLs out of saved pages (as a sanity check or regression test);
      $MODE_EXTERNAL: send the query to the search engine "live", parse the results, and compare them to the previously saved results;
    and
      $MODE_UPDATE: send the query to the search engine "live", parse the results, and save them for future testing.

  relevant_test
    Given the name of a backend, returns true if this Test object is able to
    test that backend.

  eval_test
    Given the name of a backend, grabs the $TEST_CASES variable from that
    backend and evaluates it.

  test
    Run test(s) for a backend. Arguments are, in order: name of a backend to
    test (string, required); name of backend maintainer (string, if undef
    $backend::MAINTAINER will be used); filename for results
    storage/comparison (string, required); query to be sent to backend
    (string, required); test method (required, one of the following).

    Several test methods are possible:

      $TEST_EXACTLY: list of URLs must match exactly (line for line, in order);
      $TEST_BY_COUNTING: test passes if number of resulting URLs is equal;
      $TEST_GREATER_THAN: test passes if we get more than N result URLs;
    and
      $TEST_RANGE: like $TEST_GREATER_THAN but constrained on both ends.

  no_test
    Prints a message stating that this backend does not have a test suite.
    Takes two arguments, the backend name and the name of the maintainer.

  not_working
    Prints a message stating that this backend is known to be broken. Takes
    two arguments, the backend name and the name of the maintainer.

  not_working_with_tests
    Prints a message stating that this backend is known to be broken even
    though it has a test suite. Takes two arguments, the backend name and
    the name of the maintainer.

  not_working_and_abandoned
    Prints a message stating that this backend is known to be broken and is
    not being actively maintained. Takes two arguments, the backend name and
    the name of the maintainer.

  reset_error_count
    Reset the counter of errors to zero. You probably want to call this
    before each call to test() or eval_test().

  wc_l (private, not a method)
    Given a filename, count the number of lines of text contained within the
    file. (I.e. simulate running UNIX command "wc -l" on a file)

  diff (private, not a method)
    Given two files, returns TRUE if contents are line-by-line different, or
    FALSE if contents are line-by-line same. (I.e. like the UNIX command
    diff, but just reports true or false)

  Shortcuts for running backend tests
    WWW::Search::Test keeps its own count of test numbers, so if you want to
    mix-and-match these functions with your own tests, use the
    $WWW::Search::Test::iTest counter.

  new_engine
    One argument: the name of a backend suitable to be passed to
    WWW::Search::new(). Prints 'ok' or 'not ok' and the test number. Creates
    a WWW::Search object internally, to be used for all subsequent calls to
    run_test and run_gui_test (see below).

  tm_new_engine
    Same as new_engine(), but uses Test::More instead of just printing 'ok'.

  run_test
    Three arguments: a query string, NOT escaped; a minimum number of
    expected results; and a maximum number of expected results. Optional
    fourth argument: integer value to be used as the search_debug. Optional
    fifth argument: send any true value to dump the search results. Optional
    sixth argument: reference to hash of search options (see backend
    documentation). Optional seventh argument: send any true value to NOT
    escape the query string.

    If the minimum is undef, assumes zero. If the maximum is undef, does not
    check.

    Prints 'ok' or 'not ok' and the test number.

  run_gui_test
    Same as run_test(), but calls gui_query() instead of native_query().

  tm_run_test
    Same as run_test(), but uses Test::More rather than just printing 'ok'.

    Note: If you use this function inside a TODO block, you must set global
    variable $TODO rather than a local $TODO, and you must set the global
    $TODO back to empty-string (or undef) at the end of your TODO block. For
    example:

      TODO:
        {
        $TODO = 'I have not fixed this yet';
        tm_run_test(...);
        $TODO = '';
        } # end of TODO block

  tm_run_test_no_approx
    Same as tm_run_test, but does NOT check the approximate_result_count.

  count_results
    Run a query, and return the actual (not approximate) number of hits.
    Required first argument determines which backend query method to call:
    'gui' to call gui_query(), anything else to call native_query().
    Remaining arguments are same as all the run_test() arguments.

  skip_test
    You can call this function instead of run_test() or run_gui_test() if
    the current test must be skipped for any reason.

  test_most_results
    Given an arrayref of things to test, runs all those things against all
    the results of the most-recently executed test search.