.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "WWW::Search::Test 3pm"
.TH WWW::Search::Test 3pm "2020-09-10" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
WWW::Search::Test \- utilities to aid in testing WWW::Search backends
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  $oTest = new WWW::Search::Test(\*(AqHotBot,Yahoo,Excite\*(Aq);
\&  $oTest\->test(\*(AqHotBot\*(Aq, \*(AqKingpin\*(Aq, \*(Aqone\*(Aq, $sQuery, $TEST_RANGE, 1, 10);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
See file test.pl in the WWW-Search-HotBot distribution for a detailed
\&\*(L"real-world\*(R" example.
.SH "METHODS AND FUNCTIONS"
.IX Header "METHODS AND FUNCTIONS"
.SS "find_websearch"
.IX Subsection "find_websearch"
Returns the full path of an executable WebSearch program,
or undef if none can be found.
.SS "new"
.IX Subsection "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.
.SS "mode"
.IX Subsection "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.
.PP
There are three test modes available.  They are:
.PP
.Vb 4
\&  $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.
.Ve
.SS "relevant_test"
.IX Subsection "relevant_test"
Given the name of a backend,
returns true if this Test object is able to test that backend.
.SS "eval_test"
.IX Subsection "eval_test"
Given the name of a backend,
grabs the \f(CW$TEST_CASES\fR variable from that backend and evaluates it.
.SS "test"
.IX Subsection "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 \f(CW$backend::MAINTAINER\fR 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).
.PP
Several test methods are possible:
.PP
.Vb 5
\&  $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.
.Ve
.SS "no_test"
.IX Subsection "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.
.SS "not_working"
.IX Subsection "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.
.SS "not_working_with_tests"
.IX Subsection "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.
.SS "not_working_and_abandoned"
.IX Subsection "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.
.SS "reset_error_count"
.IX Subsection "reset_error_count"
Reset the counter of errors to zero.
You probably want to call this before each call to \fBtest()\fR or \fBeval_test()\fR.
.SS "wc_l (private, not a method)"
.IX Subsection "wc_l (private, not a method)"
Given a filename, count the number of lines of text contained
within the file.  
(I.e. simulate running \s-1UNIX\s0 command \f(CW\*(C`wc \-l\*(C'\fR on a file)
.SS "diff (private, not a method)"
.IX Subsection "diff (private, not a method)"
Given two files, returns \s-1TRUE\s0 if contents are line-by-line
different, or \s-1FALSE\s0 if contents are line-by-line same.
(I.e. like the \s-1UNIX\s0 command diff, but just reports true or false)
.SS "Shortcuts for running backend tests"
.IX Subsection "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 \f(CW$WWW::Search::Test::iTest\fR counter.
.SS "new_engine"
.IX Subsection "new_engine"
One argument: the name of a backend suitable to be passed to \fBWWW::Search::new()\fR.
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).
.SS "tm_new_engine"
.IX Subsection "tm_new_engine"
Same as \fBnew_engine()\fR, but uses Test::More instead of just printing 'ok'.
.SS "run_test"
.IX Subsection "run_test"
Three arguments: a query string, \s-1NOT\s0 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 \s-1NOT\s0 escape the query string.
.PP
If the minimum is undef, assumes zero.
If the maximum is undef, does not check.
.PP
Prints 'ok' or 'not ok' and the test number.
.SS "run_gui_test"
.IX Subsection "run_gui_test"
Same as \fBrun_test()\fR, but calls \fBgui_query()\fR instead of \fBnative_query()\fR.
.SS "tm_run_test"
.IX Subsection "tm_run_test"
Same as \fBrun_test()\fR, but uses Test::More rather than just printing 'ok'.
.PP
Note: If you use this function inside a \s-1TODO\s0 block,
you must set global variable \f(CW$TODO\fR rather than a local \f(CW$TODO\fR,
and you must set the global \f(CW$TODO\fR back to empty-string (or undef) at the end of your \s-1TODO\s0 block.
For example:
.PP
.Vb 6
\&  TODO:
\&    {
\&    $TODO = \*(AqI have not fixed this yet\*(Aq;
\&    tm_run_test(...);
\&    $TODO = \*(Aq\*(Aq;
\&    } # end of TODO block
.Ve
.SS "tm_run_test_no_approx"
.IX Subsection "tm_run_test_no_approx"
Same as tm_run_test, but does \s-1NOT\s0 check the approximate_result_count.
.SS "count_results"
.IX Subsection "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 \fBgui_query()\fR, anything else to call \fBnative_query()\fR.
Remaining arguments are same as all the \fBrun_test()\fR arguments.
.SS "skip_test"
.IX Subsection "skip_test"
You can call this function instead of \fBrun_test()\fR or \fBrun_gui_test()\fR
if the current test must be skipped for any reason.
.SS "test_most_results"
.IX Subsection "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.