.\" Automatically generated by Pod::Man 4.10 (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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PRIVOXY-REGRESSION-TEST 1"
.TH PRIVOXY-REGRESSION-TEST 1 "2021-03-08" "perl v5.28.1" "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"
privoxy\-regression\-test \- A regression test "framework" for Privoxy.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBprivoxy-regression-test\fR [\fB\-\-debug bitmask\fR] [\fB\-\-forks\fR forks]
[\fB\-\-fuzzer\-feeding\fR] [\fB\-\-fuzzer\-feeding\fR] [\fB\-\-help\fR] [\fB\-\-level level\fR]
[\fB\-\-local\-test\-file testfile\fR] [\fB\-\-loops count\fR] [\fB\-\-max\-level max-level\fR]
[\fB\-\-max\-time max-time\fR] [\fB\-\-min\-level min-level\fR] \fB\-\-privoxy\-address proxy-address\fR
[\fB\-\-retries retries\fR] [\fB\-\-test\-number test-number\fR]
[\fB\-\-show\-skipped\-tests\fR] [\fB\-\-sleep\-time\fR seconds] [\fB\-\-verbose\fR]
[\fB\-\-version\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Privoxy-Regression-Test is supposed to one day become
a regression test suite for Privoxy. It's not quite there
yet, however, and can currently only test header actions,
check the returned status code for requests to arbitrary
URLs and verify which actions are applied to them.
.PP
Client header actions are tested by requesting
\&\fBhttp://p.p/show\-request\fR and checking whether
or not Privoxy modified the original request as expected.
.PP
The original request contains both the header the action-to-be-tested
acts upon and an additional tagger-triggering header that enables
the action to test.
.PP
Applied actions are checked through \fBhttp://p.p/show\-url\-info\fR.
.SH "CONFIGURATION FILE SYNTAX"
.IX Header "CONFIGURATION FILE SYNTAX"
Privoxy-Regression-Test's configuration is embedded in
Privoxy action files and loaded through Privoxy's web interface.
.PP
It makes testing a Privoxy version running on a remote system easier
and should prevent you from updating your tests without updating Privoxy's
configuration accordingly.
.PP
A client-header-action test section looks like this:
.PP
.Vb 4
\&    # Set Header    = Referer: http://www.example.org.zwiebelsuppe.exit/
\&    # Expect Header = Referer: http://www.example.org/
\&    {+client\-header\-filter{hide\-tor\-exit\-notation} \-hide\-referer}
\&    TAG:^client\-header\-filter\e{hide\-tor\-exit\-notation\e}$
.Ve
.PP
The example above causes Privoxy-Regression-Test to set
the header \fBReferer: http://www.example.org.zwiebelsuppe.exit/\fR
and to expect it to be modified to
\&\fBReferer: http://www.example.org/\fR.
.PP
When testing this section, Privoxy-Regression-Test will set the header
\&\fBX\-Privoxy-Control: client\-header\-filter{hide\-tor\-exit\-notation}\fR
causing the \fBprivoxy-control\fR tagger to create the tag
\&\fBclient\-header\-filter{hide\-tor\-exit\-notation}\fR which will finally
cause Privoxy to enable the action section.
.PP
Note that the actions itself are only used by Privoxy,
Privoxy-Regression-Test ignores them and will be happy
as long as the expectations are satisfied.
.PP
A fetch test looks like this:
.PP
.Vb 2
\&    # Fetch Test = http://p.p/user\-manual
\&    # Expect Status Code = 302
.Ve
.PP
It tells Privoxy-Regression-Test to request \fBhttp://p.p/user\-manual\fR
and to expect a response with the \s-1HTTP\s0 status code \fB302\fR. Obviously that's
not a very thorough test and mainly useful to get some code coverage
for Valgrind or to verify that the templates are installed correctly.
.PP
If you want to test \s-1CGI\s0 pages that require a trusted
referer, you can use:
.PP
.Vb 1
\&    # Trusted CGI Request = http://p.p/edit\-actions
.Ve
.PP
It works like ordinary fetch tests, but sets the referer
header to a trusted value.
.PP
If no explicit status code expectation is set, \fB200\fR is used.
.PP
To verify that a \s-1URL\s0 is blocked, use:
.PP
.Vb 1
\&    # Blocked URL = http://www.example.com/blocked
.Ve
.PP
To verify that a specific set of actions is applied to an \s-1URL,\s0 use:
.PP
.Vb 2
\&    # Sticky Actions = +block{foo} +handle\-as\-empty\-document \-handle\-as\-image
\&    # URL = http://www.example.org/my\-first\-url
.Ve
.PP
The sticky actions will be checked for all URLs below it
until the next sticky actions directive.
.PP
To verify that requests for a \s-1URL\s0 get redirected, use:
.PP
.Vb 2
\&    # Redirected URL = http://www.example.com/redirect\-me
\&    # Redirect Destination = http://www.example.org/redirected
.Ve
.PP
To skip a test, add the following line:
.PP
.Vb 1
\&    # Ignore = Yes
.Ve
.PP
The difference between a skipped test and a removed one is that removing
a test affects the numbers of the following tests, while a skipped test
is still loaded and thus keeps the test numbers unchanged.
.PP
Sometimes user modifications intentionally conflict with tests in the
default configuration and thus cause test failures. Adding the Ignore
directive to the failing tests works but is inconvenient as the directive
is likely to get lost with the next update.
.PP
Overwrite conditions are an alternative and can be added in any action
file as long as the come after the test that is expected to fail.
They causes all previous tests a matching the condition to be skipped.
.PP
It is recommended to put the overwrite condition below the custom Privoxy
section that causes the expected test failure and before the custom test
that verifies that tests the now expected behaviour. Example:
.PP
.Vb 8
\&    # The following section is expected to overwrite a section in
\&    # default.action, whose effect is being tested. Thus also disable
\&    # the test that is now expected to fail and add a new one.
\&    #
\&    {+block{Facebook makes Firefox even more unstable. Do not want.}}
\&    # Overwrite condition = http://apps.facebook.com/onthefarm/track.php?creative=&cat=friendvisit&subcat=weeds&key=a789a971dc687bee4c20c044834fabdd&next=index.php%3Fref%3Dnotif%26visitId%3D898835505
\&    # Blocked URL = http://apps.facebook.com/
\&    .facebook./
.Ve
.SH "TEST LEVELS"
.IX Header "TEST LEVELS"
All tests have test levels to let the user
control which ones to execute (see \fI\s-1OPTIONS\s0\fR below). 
Test levels are either set with the \fBLevel\fR directive,
or implicitly through the test type.
.PP
Redirect tests default to level 108, block tests to level 7,
fetch tests to level 6, \*(L"Sticky Actions\*(R" tests default to
level 5, tests for trusted \s-1CGI\s0 requests to level 3 and
client-header-action tests to level 1.
.PP
The current redirect test level is above the default
max-level value as failed tests will result in outgoing
connections. Use the \fB\-\-max\-level\fR option to run them
as well.
.PP
The \*(L"Default level offset\*(R" directive can be used to change
the default level by a given value. This directive affects
all tests located after it until the end of the file or a another
\&\*(L"Default level offset\*(R" directive is reached. The purpose of this
directive is to make it more convenient to skip similar tests in
a given file without having to remove or disable the tests completely.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fB\-\-debug bitmask\fR Add the bitmask provided as integer
to the debug settings.
.PP
\&\fB\-\-forks forks\fR Number of forks to start before executing
the regression tests. This is mainly useful for stress-testing.
.PP
\&\fB\-\-fuzzer\-address\fR Listening address used when executing
the regression tests. Useful to make sure that the requests
to load the regression tests don't fail due to fuzzing.
.PP
\&\fB\-\-fuzzer\-feeding\fR Ignore some errors that would otherwise
cause Privoxy-Regression-Test to abort the test because
they shouldn't happen in normal operation. This option is
intended to be used if Privoxy-Regression-Test is only
used to feed a fuzzer in which case there's a high chance
that Privoxy gets an invalid request and returns an error
message.
.PP
\&\fB\-\-help\fR Shows available command line options.
.PP
\&\fB\-\-header\-fuzzing\fR Modifies linear white space in
headers in a way that should not affect the test result.
.PP
\&\fB\-\-level level\fR Only execute tests with the specified \fBlevel\fR.
.PP
\&\fB\-\-local\-test\-file test-file\fR Do not get the tests
through Privoxy's web interface, but use a single local
file. Not recommended for testing Privoxy, but can be useful
to \*(L"misappropriate\*(R" Privoxy-Regression-Test to test other
stuff, like webserver configurations.
.PP
\&\fB\-\-loop count\fR Loop through the regression tests \fBcount\fR times. 
Useful to feed a fuzzer, or when doing stress tests with
several Privoxy-Regression-Test instances running at the same
time.
.PP
\&\fB\-\-max\-level max-level\fR Only execute tests with a \fBlevel\fR
below or equal to the numerical \fBmax-level\fR.
.PP
\&\fB\-\-max\-time max-time\fR Give Privoxy \fBmax-time\fR seconds
to return data. Increasing the default may make sense when
Privoxy is run through Valgrind, decreasing the default may
make sense when Privoxy-Regression-Test is used to feed
a fuzzer.
.PP
\&\fB\-\-min\-level min-level\fR Only execute tests with a \fBlevel\fR
above or equal to the numerical \fBmin-level\fR.
.PP
\&\fB\-\-privoxy\-address proxy-address\fR Privoxy's listening address.
If it's not set, the value of the environment variable http_proxy
will be used. \fBproxy-address\fR has to be specified in http_proxy
syntax.
.PP
\&\fB\-\-retries retries\fR Retry \fBretries\fR times.
.PP
\&\fB\-\-test\-number test-number\fR Only run the test with the specified
number.
.PP
\&\fB\-\-show\-skipped\-tests\fR Log skipped tests even if verbose mode is off.
.PP
\&\fB\-\-shuffle\-tests\fR Shuffle test sections and their tests before
executing them. When combined with \fB\-\-forks\fR, this can increase
the chances of detecting race conditions. Of course some problems
are easier to detect without this option.
.PP
\&\fB\-\-sleep\-time seconds\fR Wait \fBseconds\fR between tests. Useful when
debugging issues with systems that don't log with millisecond precision.
.PP
\&\fB\-\-verbose\fR Log successful tests as well. By default only
the failures are logged.
.PP
\&\fB\-\-version\fR Print version and exit.
.PP
The second dash is optional, options can be shortened,
as long as there are no ambiguities.
.SH "PRIVOXY CONFIGURATION"
.IX Header "PRIVOXY CONFIGURATION"
Privoxy-Regression-Test is shipped with \fBregression\-tests.action\fR
which aims to test all official client-header modifying actions
and can be used to verify that the templates and the user manual
files are installed correctly.
.PP
To use it, it has to be copied in Privoxy's configuration
directory, and afterwards referenced in Privoxy's configuration
file with the line:
.PP
.Vb 1
\&    actionsfile regression\-tests.action
.Ve
.PP
In general, its tests are supposed to work without changing
any other action files, unless you already added lots of
taggers yourself. If you are using taggers that cause problems,
you might have to temporary disable them for Privoxy's \s-1CGI\s0 pages.
.PP
Some of the regression tests rely on Privoxy features that
may be disabled in your configuration. Tests with a level below
7 are supposed to work with all Privoxy configurations (provided
you didn't build with \s-1FEATURE_GRACEFUL_TERMINATION\s0).
.PP
Tests with level 9 require Privoxy to deliver the User Manual,
tests with level 12 require the \s-1CGI\s0 editor to be enabled.
.SH "CAVEATS"
.IX Header "CAVEATS"
Expect the configuration file syntax to change with future releases.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
As Privoxy's \fBshow-request\fR page only shows client headers,
Privoxy-Regression-Test can't use it to test Privoxy actions
that modify server headers.
.PP
As Privoxy-Regression-Test relies on Privoxy's tag feature to
control the actions to test, it currently only works with
Privoxy 3.0.7 or later.
.PP
At the moment Privoxy-Regression-Test fetches Privoxy's
configuration page through \fIcurl\fR(1), therefore you have to
have \fIcurl\fR installed, otherwise you won't be able to run
Privoxy-Regression-Test in a meaningful way.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBprivoxy\fR\|(1) \fBcurl\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
Fabian Keil <fk@fabiankeil.de>