tools/privoxy-regression-test.pl

   1 #!/usr/bin/perl
   2
   3 ############################################################################
   4 #
   5 # Privoxy-Regression-Test
   6 #
   7 # A regression test "framework" for Privoxy. For documentation see:
   8 # perldoc privoxy-regression-test.pl
   9 #
  10 # $Id: privoxy-regression-test.pl,v 1.135 2008/03/26 10:58:46 fk Exp $
  11 #
  12 # Wish list:
  13 #
  14 # - Update documentation
  15 # - Validate HTTP times.
  16 # - Understand default.action.master comment syntax
  17 #   and verify that we actually block and unblock what
  18 #   the comments claim we do.
  19 # - Implement a HTTP_VERSION directive or allow to
  20 #   specify whole request lines.
  21 # - Support filter regression tests.
  22 # - Add option to fork regression tests and run them in parallel,
  23 #   possibly optional forever.
  24 # - Document magic Expect Header values
  25 # - Internal fuzz support?
  26 #
  27 # Copyright (c) 2007-2008 Fabian Keil <fk@fabiankeil.de>
  28 #
  29 # Permission to use, copy, modify, and distribute this software for any
  30 # purpose with or without fee is hereby granted, provided that the above
  31 # copyright notice and this permission notice appear in all copies.
  32 #
  33 # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  34 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  35 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  36 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  37 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  38 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  39 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  40 #
  41 ############################################################################
  42
  43 use warnings;
  44 use strict;
  45 use Getopt::Long;
  46
  47 use constant {
  48                PRT_VERSION => 'Privoxy-Regression-Test 0.2',
  49
  50                CURL => 'curl',
  51
  52                # CLI option defaults
  53                CLI_RETRIES  => 1,
  54                CLI_LOOPS    => 1,
  55                CLI_MAX_TIME => 5,
  56                CLI_MIN_LEVEL => 0,
  57                CLI_MAX_LEVEL => 25,
  58
  59                PRIVOXY_CGI_URL => 'http://p.p/',
  60                FELLATIO_URL    => 'http://10.0.0.1:8080/',
  61                LEADING_LOG_DATE => 1,
  62                LEADING_LOG_TIME => 1,
  63
  64                DEBUG_LEVEL_FILE_LOADING    => 0,
  65                DEBUG_LEVEL_PAGE_FETCHING   => 0,
  66
  67                VERBOSE_TEST_DESCRIPTION    => 1,
  68
  69                DEBUG_LEVEL_VERBOSE_FAILURE => 1,
  70                # XXX: Only partly implemented and mostly useless.
  71                DEBUG_LEVEL_VERBOSE_SUCCESS => 0,
  72                DEBUG_LEVEL_STATUS          => 1,
  73
  74                # Internal use, don't modify
  75                # Available debug bits:
  76                LL_ERROR                   =>  1,
  77                LL_VERBOSE_FAILURE         =>  2,
  78                LL_PAGE_FETCHING           =>  4,
  79                LL_FILE_LOADING            =>  8,
  80                LL_VERBOSE_SUCCESS         => 16,
  81                LL_STATUS                  => 32,
  82                LL_SOFT_ERROR              => 64,
  83
  84                CLIENT_HEADER_TEST         =>  1,
  85                SERVER_HEADER_TEST         =>  2,
  86                DUMB_FETCH_TEST            =>  3,
  87                METHOD_TEST                =>  4,
  88                STICKY_ACTIONS_TEST        =>  5,
  89                TRUSTED_CGI_REQUEST        =>  6,
  90                BLOCK_TEST                 =>  7,
  91 };
  92
  93 sub init_our_variables () {
  94
  95     our $leading_log_time = LEADING_LOG_TIME;
  96     our $leading_log_date = LEADING_LOG_DATE;
  97
  98     our $privoxy_cgi_url  = PRIVOXY_CGI_URL;
  99
 100     our $verbose_test_description = VERBOSE_TEST_DESCRIPTION;
 101
 102     our $log_level = get_default_log_level();
 103
 104 }
 105
 106 sub get_default_log_level () {
 107
 108     my $log_level = 0;
 109
 110     $log_level |= LL_FILE_LOADING    if DEBUG_LEVEL_FILE_LOADING;
 111     $log_level |= LL_PAGE_FETCHING   if DEBUG_LEVEL_PAGE_FETCHING;
 112     $log_level |= LL_VERBOSE_FAILURE if DEBUG_LEVEL_VERBOSE_FAILURE;
 113     $log_level |= LL_VERBOSE_SUCCESS if DEBUG_LEVEL_VERBOSE_SUCCESS;
 114     $log_level |= LL_STATUS          if DEBUG_LEVEL_STATUS;
 115
 116     # These are intended to be always on.
 117     $log_level |= LL_SOFT_ERROR;
 118     $log_level |= LL_ERROR;
 119
 120     return $log_level;
 121 }
 122
 123 ############################################################################
 124 #
 125 # File loading functions
 126 #
 127 ############################################################################
 128
 129 sub parse_tag ($) {
 130
 131     my $tag = shift;
 132
 133     # Remove anchors
 134     $tag =~ s@[\$\^]@@g;
 135     # Unescape brackets and dots
 136     $tag =~ s@\\(?=[{}().+])@@g;
 137
 138     # log_message("Parsed tag: " . $tag);
 139
 140     check_for_forbidden_characters($tag);
 141
 142     return $tag;
 143 }
 144
 145 sub check_for_forbidden_characters ($) {
 146
 147     my $tag = shift; # XXX: also used to check values though.
 148     my $allowed = '[-=\dA-Za-z~{}:.\/();\s,+@"_%\?&*^]';
 149
 150     unless ($tag =~ m/^$allowed*$/) {
 151         my $forbidden = $tag;
 152         $forbidden =~ s@^$allowed*(.).*@$1@;
 153
 154         l(LL_ERROR, "'" . $tag . "' contains character '" . $forbidden. "' which is unacceptable.");
 155     }
 156 }
 157
 158 sub load_regressions_tests () {
 159
 160     our $privoxy_cgi_url;
 161     our @privoxy_config;
 162     my @actionfiles;
 163     my $curl_url = '';
 164     my $file_number = 0;
 165
 166     $curl_url .= $privoxy_cgi_url;
 167     $curl_url .= 'show-status';
 168
 169     l(LL_STATUS, "Asking Privoxy for the number of action files available ...");
 170
 171     foreach (@{get_cgi_page_or_else($curl_url)}) {
 172
 173         chomp;
 174         if (/<td>(.*?)<\/td><td class=\"buttons\"><a href=\"\/show-status\?file=actions&amp;index=(\d+)\">/) {
 175
 176             my $url = $privoxy_cgi_url . 'show-status?file=actions&index=' . $2;
 177             $actionfiles[$file_number++] = $url;
 178
 179         } elsif (m@config\.html#.*\">([^<]*)</a>\s+(.*)<br>@) {
 180
 181             my $directive = $1 . " " . $2;
 182             push (@privoxy_config, $directive);
 183         }
 184     }
 185
 186     l(LL_FILE_LOADING, "Recognized " . @actionfiles . " actions files");
 187
 188     load_action_files(\@actionfiles);
 189 }
 190
 191 sub token_starts_new_test ($) {
 192
 193     my $token = shift;
 194     my @new_test_directives = ('set header', 'fetch test',
 195          'trusted cgi request', 'request header', 'method test',
 196          'blocked url', 'url');
 197
 198     foreach my $new_test_directive (@new_test_directives) {
 199         return 1 if $new_test_directive eq $token;
 200     }
 201     return 0;
 202
 203 }
 204
 205 sub tokenize ($) {
 206
 207     my ($token, $value) = (undef, undef);
 208
 209     # Remove leading and trailing white space.
 210     s@^\s*@@;
 211     s@\s*$@@;
 212
 213     # Reverse HTML-encoding
 214     # XXX: Seriously imcomplete.
 215     s@&quot;@"@g;
 216     s@&amp;@&@g;
 217
 218     # Tokenize
 219     if (/^\#\s*([^=:]*?)\s*[=]\s*(.+?)\s*$/) {
 220
 221         $token = $1;
 222         $value = $2;
 223
 224         $token =~ s@\s\s+@ @g;
 225         $token =~ tr/[A-Z]/[a-z]/;
 226
 227     } elsif (/^TAG\s*:(.*)$/) {
 228
 229         $token = 'tag';
 230         $value = $1;
 231
 232     }
 233
 234     return ($token, $value);
 235 }
 236
 237 sub enlist_new_test ($$$$$$) {
 238
 239     my ($regression_tests, $token, $value, $si, $ri, $number) = @_;
 240
 241     if ($token eq 'set header') {
 242
 243         l(LL_FILE_LOADING, "Header to set: " . $value);
 244         ${$regression_tests}[$si][$ri]{'type'} = CLIENT_HEADER_TEST;
 245         # Implicit default
 246         $$regression_tests[$si][$ri]{'level'} = CLIENT_HEADER_TEST;
 247
 248     } elsif ($token eq 'request header') {
 249
 250         l(LL_FILE_LOADING, "Header to request: " . $value);
 251         $$regression_tests[$si][$ri]{'type'} = SERVER_HEADER_TEST;
 252         # Implicit default
 253         $$regression_tests[$si][$ri]{'expected-status-code'} = 200;
 254         $$regression_tests[$si][$ri]{'level'} = SERVER_HEADER_TEST;
 255
 256     } elsif ($token eq 'trusted cgi request') {
 257
 258         l(LL_FILE_LOADING, "CGI URL to test in a dumb way: " . $value);
 259         $$regression_tests[$si][$ri]{'type'} = TRUSTED_CGI_REQUEST;
 260         # Implicit default
 261         $$regression_tests[$si][$ri]{'expected-status-code'} = 200;
 262         $$regression_tests[$si][$ri]{'level'} = TRUSTED_CGI_REQUEST;
 263
 264     } elsif ($token eq 'fetch test') {
 265
 266         l(LL_FILE_LOADING, "URL to test in a dumb way: " . $value);
 267         $$regression_tests[$si][$ri]{'type'} = DUMB_FETCH_TEST;
 268         # Implicit default
 269         $$regression_tests[$si][$ri]{'expected-status-code'} = 200;
 270         $$regression_tests[$si][$ri]{'level'} = DUMB_FETCH_TEST;
 271
 272     } elsif ($token eq 'method test') {
 273
 274         l(LL_FILE_LOADING, "Method to test: " . $value);
 275         $$regression_tests[$si][$ri]{'type'} = METHOD_TEST;
 276         # Implicit default
 277         $$regression_tests[$si][$ri]{'expected-status-code'} = 200;
 278         $$regression_tests[$si][$ri]{'level'} = METHOD_TEST;
 279
 280     } elsif ($token eq 'blocked url') {
 281
 282         l(LL_FILE_LOADING, "URL to block-test: " . $value);
 283         $$regression_tests[$si][$ri]{'type'} = BLOCK_TEST;
 284         # Implicit default
 285         $$regression_tests[$si][$ri]{'expected-status-code'} = 403;
 286         $$regression_tests[$si][$ri]{'level'} = BLOCK_TEST;
 287
 288     } elsif ($token eq 'url') {
 289
 290         l(LL_FILE_LOADING, "Sticky URL to test: " . $value);
 291         $$regression_tests[$si][$ri]{'type'} = STICKY_ACTIONS_TEST;
 292         # Implicit default
 293         $$regression_tests[$si][$ri]{'level'} = STICKY_ACTIONS_TEST;
 294         $$regression_tests[$si][$ri]{'url'} = '';
 295
 296     } else {
 297
 298         die "Incomplete '" . $token . "' support detected.";
 299
 300     }
 301
 302     check_for_forbidden_characters($value);
 303
 304     $$regression_tests[$si][$ri]{'data'} = $value;
 305
 306     # For function that only get passed single tests
 307     $$regression_tests[$si][$ri]{'section-id'} = $si;
 308     $$regression_tests[$si][$ri]{'regression-test-id'} = $ri;
 309     $$regression_tests[$si][$ri]{'number'} = $number - 1;
 310     l(LL_FILE_LOADING,
 311       "Regression test " . $number . " (section:" . $si . "):");
 312 }
 313
 314 sub load_action_files ($) {
 315
 316     # initialized here
 317     our %actions;
 318     our @regression_tests;
 319
 320     my $actionfiles_ref = shift;
 321     my @actionfiles = @{$actionfiles_ref};
 322
 323     my $si = 0;  # Section index
 324     my $ri = -1; # Regression test index
 325     my $count = 0;
 326
 327     my $ignored = 0;
 328
 329     l(LL_STATUS, "Loading regression tests from action file(s) delivered by Privoxy.");
 330
 331     for my $file_number (0 .. @actionfiles - 1) {
 332
 333         my $curl_url = ' "' . $actionfiles[$file_number] . '"';
 334         my $actionfile = undef;
 335         my $sticky_actions = undef;
 336
 337         foreach (@{get_cgi_page_or_else($curl_url)}) {
 338
 339             my $no_checks = 0;
 340             chomp;
 341
 342             if (/<h2>Contents of Actions File (.*?)</) {
 343                 $actionfile = $1;
 344                 next;
 345             }
 346             next unless defined $actionfile;
 347
 348             last if (/<\/pre>/);
 349
 350             my ($token, $value) = tokenize($_);
 351
 352             next unless defined $token;
 353
 354             # Load regression tests
 355
 356             if (token_starts_new_test($token)) {
 357
 358                 # Beginning of new regression test.
 359                 $ri++;
 360                 $count++;
 361                 enlist_new_test(\@regression_tests, $token, $value, $si, $ri, $count);
 362             }
 363
 364             if ($token =~ /level\s+(\d+)/i) {
 365
 366                 my $level = $1;
 367                 register_dependency($level, $value);
 368             }
 369
 370             if ($si == -1 || $ri == -1) {
 371                 # No beginning of a test detected yet,
 372                 # so we don't care about any other test
 373                 # attributes.
 374                 next;
 375             }
 376
 377             if ($token eq 'expect header') {
 378
 379                 l(LL_FILE_LOADING, "Detected expectation: " . $value);
 380                 $regression_tests[$si][$ri]{'expect-header'} = $value;
 381
 382             } elsif ($token eq 'tag') {
 383
 384                 next if ($ri == -1);
 385
 386                 my $tag = parse_tag($value);
 387
 388                 # We already checked in parse_tag() after filtering
 389                 $no_checks = 1;
 390
 391                 l(LL_FILE_LOADING, "Detected TAG: " . $tag);
 392
 393                 # Save tag for all tests in this section
 394                 do {
 395                     $regression_tests[$si][$ri]{'tag'} = $tag;
 396                 } while ($ri-- > 0);
 397
 398                 $si++;
 399                 $ri = -1;
 400
 401             } elsif ($token eq 'ignore' && $value =~ /Yes/i) {
 402
 403                 l(LL_FILE_LOADING, "Ignoring section: " . test_content_as_string($regression_tests[$si][$ri]));
 404                 $regression_tests[$si][$ri]{'ignore'} = 1;
 405                 $ignored++;
 406
 407             } elsif ($token eq 'expect status code') {
 408
 409                 l(LL_FILE_LOADING, "Expecting status code: " . $value);
 410                 $regression_tests[$si][$ri]{'expected-status-code'} = $value;
 411
 412             } elsif ($token eq 'level') { # XXX: stupid name
 413
 414                 $value =~ s@(\d+).*@$1@;
 415                 l(LL_FILE_LOADING, "Level: " . $value);
 416                 $regression_tests[$si][$ri]{'level'} = $value;
 417
 418             } elsif ($token eq 'method') {
 419
 420                 l(LL_FILE_LOADING, "Method: " . $value);
 421                 $regression_tests[$si][$ri]{'method'} = $value;
 422
 423             } elsif ($token eq 'sticky actions') {
 424
 425                 # Will be used by each following Sticky URL.
 426                 $sticky_actions = $value;
 427                 if ($sticky_actions =~ /{[^}]*\s/) {
 428                     l(LL_ERROR,
 429                       "'Sticky Actions' with whitespace inside the " .
 430                       "action parameters are currently unsupported.");
 431                 }
 432
 433             } elsif ($token eq 'url') {
 434
 435                 if (defined $sticky_actions) {
 436                     die "What" if defined ($regression_tests[$si][$ri]{'sticky-actions'});
 437                     l(LL_FILE_LOADING, "Sticky actions: " . $sticky_actions);
 438                     $regression_tests[$si][$ri]{'sticky-actions'} = $sticky_actions;
 439                 } else {
 440                     l(LL_FILE_LOADING, "Sticky URL without Sticky Actions");
 441                 }
 442
 443             } else {
 444
 445                 # We don't use it, so we don't need
 446                 $no_checks = 1;
 447             }
 448             # XXX: Neccessary?
 449             check_for_forbidden_characters($value) unless $no_checks;
 450             check_for_forbidden_characters($token);
 451         }
 452     }
 453
 454     l(LL_FILE_LOADING, "Done loading " . $count . " regression tests."
 455       . " Of which " . $ignored. " will be ignored)\n");
 456 }
 457
 458 ############################################################################
 459 #
 460 # Regression test executing functions
 461 #
 462 ############################################################################
 463
 464 sub execute_regression_tests () {
 465
 466     our @regression_tests;
 467     my $loops = get_cli_option('loops');
 468     my $all_tests    = 0;
 469     my $all_failures = 0;
 470     my $all_successes = 0;
 471
 472     unless (@regression_tests) {
 473
 474         l(LL_STATUS, "No regression tests found.");
 475         return;
 476     }
 477
 478     l(LL_STATUS, "Executing regression tests ...");
 479
 480     while ($loops-- > 0) {
 481
 482         my $successes = 0;
 483         my $tests = 0;
 484         my $failures;
 485         my $skipped = 0;
 486
 487         for my $s (0 .. @regression_tests - 1) {
 488
 489             my $r = 0;
 490
 491             while (defined $regression_tests[$s][$r]) {
 492
 493                 die "Section id mismatch" if ($s != $regression_tests[$s][$r]{'section-id'});
 494                 die "Regression test id mismatch" if ($r != $regression_tests[$s][$r]{'regression-test-id'});
 495
 496                 my $number = $regression_tests[$s][$r]{'number'};
 497
 498                 if ($regression_tests[$s][$r]{'ignore'}
 499                     or level_is_unacceptable($regression_tests[$s][$r]{'level'})
 500                     or test_number_is_unacceptable($number)) {
 501
 502                     $skipped++;
 503
 504                 } else {
 505
 506                     my $result = execute_regression_test($regression_tests[$s][$r]);
 507
 508                     log_result($regression_tests[$s][$r], $result, $tests);
 509
 510                     $successes += $result;
 511                     $tests++;
 512                 }
 513                 $r++;
 514             }
 515         }
 516         $failures = $tests - $successes;
 517
 518         log_message("Executed " . $tests . " regression tests. " .
 519             'Skipped ' . $skipped . '. ' .
 520             $successes . " successes, " . $failures . " failures.");
 521
 522         $all_tests    += $tests;
 523         $all_failures += $failures;
 524         $all_successes += $successes;
 525
 526     }
 527
 528     if (get_cli_option('loops') > 1) {
 529         log_message("Total: Executed " . $all_tests . " regression tests. " .
 530             $all_successes . " successes, " . $all_failures . " failures.");
 531     }
 532 }
 533
 534 sub level_is_unacceptable ($) {
 535     my $level = shift;
 536     return ((cli_option_is_set('level') and get_cli_option('level') != $level)
 537             or ($level < get_cli_option('min-level'))
 538             or ($level > get_cli_option('max-level'))
 539             or dependency_unsatisfied($level)
 540             );
 541 }
 542
 543 sub test_number_is_unacceptable ($) {
 544     my $test_number = shift;
 545     return (cli_option_is_set('test-number')
 546             and get_cli_option('test-number') != $test_number)
 547 }
 548
 549 sub dependency_unsatisfied ($) {
 550
 551     my $level = shift;
 552     our %dependencies;
 553     our @privoxy_config;
 554     my $dependency_problem = 0;
 555
 556     if (defined ($dependencies{$level}{'config line'})) {
 557
 558         my $dependency = $dependencies{$level}{'config line'};
 559         $dependency_problem = 1;
 560
 561         foreach (@privoxy_config) {
 562
 563              $dependency_problem = 0 if (/$dependency/);
 564         }
 565     }
 566
 567     return $dependency_problem;
 568 }
 569
 570 sub register_dependency ($$) {
 571
 572     my $level = shift;
 573     my $dependency = shift;
 574     our %dependencies;
 575
 576     if ($dependency =~ /config line\s+(.*)/) {
 577
 578        $dependencies{$level}{'config line'} = $1;
 579     }
 580 }
 581
 582 # XXX: somewhat misleading name
 583 sub execute_regression_test ($) {
 584
 585     my $test_ref = shift;
 586     my %test = %{$test_ref};
 587     my $result = 0;
 588
 589     if ($test{'type'} == CLIENT_HEADER_TEST) {
 590
 591         $result = execute_client_header_regression_test($test_ref);
 592
 593     } elsif ($test{'type'} == SERVER_HEADER_TEST) {
 594
 595         $result = execute_server_header_regression_test($test_ref);
 596
 597     } elsif ($test{'type'} == DUMB_FETCH_TEST
 598           or $test{'type'} == TRUSTED_CGI_REQUEST) {
 599
 600         $result = execute_dumb_fetch_test($test_ref);
 601
 602     } elsif ($test{'type'} == METHOD_TEST) {
 603
 604         $result = execute_method_test($test_ref);
 605
 606     } elsif ($test{'type'} == BLOCK_TEST) {
 607
 608         $result = execute_block_test($test_ref);
 609
 610     } elsif ($test{'type'} == STICKY_ACTIONS_TEST) {
 611
 612         $result = execute_sticky_actions_test($test_ref);
 613
 614     } else {
 615
 616         die "Unsupported test type detected: " . $test{'type'};
 617
 618     }
 619
 620     return $result;
 621 }
 622
 623 sub execute_method_test ($) {
 624
 625     my $test_ref = shift;
 626     my %test = %{$test_ref};
 627     my $buffer_ref;
 628     my $result = 0;
 629     my $status_code;
 630     my $method = $test{'data'};
 631
 632     my $curl_parameters = '';
 633     my $expected_status_code = $test{'expected-status-code'};
 634
 635     $curl_parameters .= '--request ' . $method . ' ';
 636     # Don't complain in case about the 'missing' body
 637     $curl_parameters .= '--head ' if ($method =~ /^HEAD$/i);
 638
 639     $curl_parameters .= PRIVOXY_CGI_URL;
 640
 641     $buffer_ref = get_page_with_curl($curl_parameters);
 642     $status_code = get_status_code($buffer_ref);
 643
 644     $result = check_status_code_result($status_code, $expected_status_code);
 645
 646     return $result;
 647 }
 648
 649 sub execute_dumb_fetch_test ($) {
 650
 651     my $test_ref = shift;
 652     my %test = %{$test_ref};
 653     my $buffer_ref;
 654     my $result = 0;
 655     my $status_code;
 656
 657     my $curl_parameters = '';
 658     my $expected_status_code = $test{'expected-status-code'};
 659
 660     if (defined $test{method}) {
 661         $curl_parameters .= '--request ' . $test{method} . ' ';
 662     }
 663     if ($test{type} == TRUSTED_CGI_REQUEST) {
 664         $curl_parameters .= '--referer ' . PRIVOXY_CGI_URL . ' ';
 665     }
 666
 667     $curl_parameters .= $test{'data'};
 668
 669     $buffer_ref = get_page_with_curl($curl_parameters);
 670     $status_code = get_status_code($buffer_ref);
 671
 672     $result = check_status_code_result($status_code, $expected_status_code);
 673
 674     return $result;
 675 }
 676
 677 sub execute_block_test ($) {
 678
 679     my $test = shift;
 680     my $url = $test->{'data'};
 681     my $final_results = get_final_results($url);
 682
 683     return defined $final_results->{'+block'};
 684 }
 685
 686 sub execute_sticky_actions_test ($) {
 687
 688     my $test = shift;
 689     my $url = $test->{'data'};
 690     my $verified_actions = 0;
 691     # XXX: splitting currently doesn't work for actions whose parameters contain spaces.
 692     my @sticky_actions = split(/\s+/, $test->{'sticky-actions'});
 693     my $final_results = get_final_results($url);
 694
 695     foreach my $sticky_action (@sticky_actions) {
 696         if (defined $final_results->{$sticky_action}) {
 697             # Exact match
 698             $verified_actions++;
 699         }elsif ($sticky_action =~ /-.*\{/ and
 700                 not defined $final_results->{$sticky_action}) {
 701             # Disabled multi actions aren't explicitly listed as
 702             # disabled and thus have to be checked by verifying
 703             # that they aren't enabled.
 704             $verified_actions++;
 705         } else {
 706             l(LL_VERBOSE_FAILURE,
 707               "Ooops. '$sticky_action' is not among the final results.");
 708         }
 709     }
 710
 711     return $verified_actions == @sticky_actions;
 712 }
 713
 714 sub get_final_results ($) {
 715
 716     my $url = shift;
 717     my $curl_parameters = '';
 718     my %final_results = ();
 719     my $final_results_reached = 0;
 720
 721     die "Unacceptable characterss in $url" if $url =~ m@[\\'"]@;
 722     # XXX: should be URL-encoded properly
 723     $url =~ s@%@%25@g;
 724     $url =~ s@\s@%20@g;
 725     $url =~ s@&@%26@g;
 726     $url =~ s@:@%3A@g;
 727     $url =~ s@/@%2F@g;
 728
 729     $curl_parameters .= "'" . PRIVOXY_CGI_URL . 'show-url-info?url=' . $url . "'";
 730
 731     foreach (@{get_cgi_page_or_else($curl_parameters)}) {
 732
 733         $final_results_reached = 1 if (m@<h2>Final results:</h2>@);
 734
 735         next unless ($final_results_reached);
 736         last if (m@</td>@);
 737
 738         if (m@<br>([-+])<a.*>([^>]*)</a>(?: (\{.*\}))?@) {
 739             my $action = $1.$2;
 740             my $parameter = $3;
 741
 742             if (defined $parameter) {
 743                 # In case the caller needs to check
 744                 # the action and it's parameter
 745                 $final_results{$action . $parameter} = 1;
 746             }
 747             # In case the action doesn't have paramters
 748             # or the caller doesn't care for the parameter.
 749             $final_results{$action} = 1;
 750         }
 751     }
 752
 753     return \%final_results;
 754 }
 755
 756 sub check_status_code_result ($$) {
 757
 758     my $status_code = shift;
 759     my $expected_status_code = shift;
 760     my $result = 0;
 761
 762     if ($expected_status_code == $status_code) {
 763
 764         $result = 1;
 765         l(LL_VERBOSE_SUCCESS,
 766           "Yay. We expected status code " . $expected_status_code . ", and received: " . $status_code . '.');
 767
 768     } elsif (cli_option_is_set('fuzzer-feeding') and $status_code == 123) {
 769
 770         l(LL_VERBOSE_FAILURE,
 771           "Oh well. Status code lost while fuzzing. Can't check if it was " . $expected_status_code . '.');
 772
 773     } else {
 774
 775         l(LL_VERBOSE_FAILURE,
 776           "Ooops. We expected status code " . $expected_status_code . ", but received: " . $status_code . '.');
 777
 778     }
 779
 780     return $result;
 781 }
 782
 783 sub execute_client_header_regression_test ($) {
 784
 785     my $test_ref = shift;
 786     my $buffer_ref;
 787     my $header;
 788     my $result = 0;
 789
 790     $buffer_ref = get_show_request_with_curl($test_ref);
 791
 792     $header = get_header($buffer_ref, $test_ref);
 793     $result = check_header_result($test_ref, $header);
 794
 795     return $result;
 796 }
 797
 798 sub execute_server_header_regression_test ($) {
 799
 800     my $test_ref = shift;
 801     my $buffer_ref;
 802     my $header;
 803     my $result = 0;
 804
 805     $buffer_ref = get_head_with_curl($test_ref);
 806
 807     $header = get_server_header($buffer_ref, $test_ref);
 808     $result = check_header_result($test_ref, $header);
 809
 810     return $result;
 811 }
 812
 813
 814 sub interpret_result ($) {
 815     my $success = shift;
 816     return $success ? "Success" : "Failure";
 817 }
 818
 819 sub check_header_result ($$) {
 820
 821     my $test_ref = shift;
 822     my $header = shift;
 823
 824     my %test = %{$test_ref};
 825     my $expect_header = $test{'expect-header'};
 826     my $success = 0;
 827
 828     $header =~ s@   @ @g if defined($header);
 829
 830     if ($expect_header eq 'NO CHANGE') {
 831
 832         if (defined($header) and $header eq $test{'data'}) {
 833
 834             $success = 1;
 835
 836         } else {
 837
 838             $header //= "REMOVAL";
 839             l(LL_VERBOSE_FAILURE,
 840               "Ooops. Got: " . $header . " while expecting: " . $expect_header);
 841         }
 842
 843     } elsif ($expect_header eq 'REMOVAL') {
 844
 845         if (defined($header) and $header eq $test{'data'}) {
 846
 847             l(LL_VERBOSE_FAILURE,
 848               "Ooops. Expected removal but: " . $header . " is still there.");
 849
 850         } else {
 851
 852             # XXX: Use more reliable check here and make sure
 853             # the header has a different name.
 854             $success = 1;
 855
 856         }
 857
 858     } elsif ($expect_header eq 'SOME CHANGE') {
 859
 860         if (defined($header) and not $header eq $test{'data'}) {
 861
 862             $success = 1;
 863
 864         } else {
 865
 866             $header //= "REMOVAL";
 867             l(LL_VERBOSE_FAILURE,
 868               "Ooops. Got: " . $header . " while expecting: SOME CHANGE");
 869         }
 870
 871
 872     } else {
 873
 874         if (defined($header) and $header eq $expect_header) {
 875
 876             $success = 1;
 877
 878         } else {
 879
 880             $header //= "'No matching header'"; # XXX: No header detected to be precise
 881             l(LL_VERBOSE_FAILURE,
 882               "Ooops. Got: " . $header . " while expecting: " . $expect_header);
 883         }
 884     }
 885     return $success;
 886 }
 887
 888 sub get_header_name ($) {
 889
 890     my $header = shift;
 891
 892     $header =~ s@(.*?: ).*@$1@;
 893
 894     return $header;
 895 }
 896
 897 sub get_header ($$) {
 898
 899     our $filtered_request = '';
 900
 901     my $buffer_ref = shift;
 902     my $test_ref = shift;
 903
 904     my %test = %{$test_ref};
 905     my @buffer = @{$buffer_ref};
 906
 907     my $expect_header = $test{'expect-header'};
 908
 909     my $line;
 910     my $processed_request_reached = 0;
 911     my $read_header = 0;
 912     my $processed_request = '';
 913     my $header;
 914     my $header_to_get;
 915
 916     if ($expect_header eq 'REMOVAL'
 917      or $expect_header eq 'NO CHANGE'
 918      or  $expect_header eq 'SOME CHANGE') {
 919
 920         $expect_header = $test{'data'};
 921
 922     }
 923
 924     $header_to_get = get_header_name($expect_header);
 925
 926     foreach (@buffer) {
 927
 928         # Skip everything before the Processed request
 929         if (/Processed Request/) {
 930             $processed_request_reached = 1;
 931             next;
 932         }
 933         next unless $processed_request_reached;
 934
 935         # End loop after the Processed request
 936         last if (/<\/pre>/);
 937
 938         # Ditch tags and leading/trailing white space.
 939         s@^\s*<.*?>@@g;
 940         s@\s*$@@g;
 941
 942         $filtered_request .=  "\n" . $_;
 943
 944         if (/^$header_to_get/) {
 945             $read_header = 1;
 946             $header = $_;
 947             last;
 948         }
 949     }
 950
 951     return $header;
 952 }
 953
 954 sub get_server_header ($$) {
 955
 956     my $buffer_ref = shift;
 957     my $test_ref = shift;
 958
 959     my %test = %{$test_ref};
 960     my @buffer = @{$buffer_ref};
 961
 962     my $expect_header = $test{'expect-header'};
 963     my $header;
 964     my $header_to_get;
 965
 966     if ($expect_header eq 'REMOVAL'
 967      or $expect_header eq 'NO CHANGE'
 968      or $expect_header eq 'SOME CHANGE') {
 969
 970         $expect_header = $test{'data'};
 971
 972     }
 973
 974     $header_to_get = get_header_name($expect_header);
 975
 976     foreach (@buffer) {
 977
 978         # XXX: should probably verify that the request
 979         # was actually answered by Fellatio.
 980         if (/^$header_to_get/) {
 981             $header = $_;
 982             $header =~ s@\s*$@@g;
 983             last;
 984         }
 985     }
 986
 987     return $header;
 988 }
 989
 990 sub get_status_code ($) {
 991
 992     my $buffer_ref = shift;
 993     my @buffer = @{$buffer_ref};
 994
 995     foreach (@buffer) {
 996
 997         if (/^HTTP\/\d\.\d (\d{3})/) {
 998
 999             return $1;
1000
1001         } else {
1002
1003             return '123' if cli_option_is_set('fuzzer-feeding');
1004             chomp;
1005             l(LL_ERROR, 'Unexpected buffer line: "' . $_ . '"');
1006         }
1007     }
1008 }
1009
1010 sub get_test_keys () {
1011     return ('tag', 'data', 'expect-header', 'ignore');
1012 }
1013
1014 # XXX: incomplete
1015 sub test_content_as_string ($) {
1016
1017     my $test_ref = shift;
1018     my %test = %{$test_ref};
1019
1020     my $s = "\n\t";
1021
1022     foreach my $key (get_test_keys()) {
1023         $test{$key} = 'Not set' unless (defined $test{$key});
1024     }
1025
1026     $s .= 'Tag: ' . $test{'tag'};
1027     $s .= "\n\t";
1028     $s .= 'Set header: ' . $test{'data'}; # XXX: adjust for other test types
1029     $s .= "\n\t";
1030     $s .= 'Expected header: ' . $test{'expect-header'};
1031     $s .= "\n\t";
1032     $s .= 'Ignore: ' . $test{'ignore'};
1033
1034     return $s;
1035 }
1036
1037 ############################################################################
1038 #
1039 # HTTP fetch functions
1040 #
1041 ############################################################################
1042
1043 sub check_for_curl () {
1044     my $curl = CURL;
1045     l(LL_ERROR, "No curl found.") unless (`which $curl`);
1046 }
1047
1048 sub get_cgi_page_or_else ($) {
1049
1050     my $cgi_url = shift;
1051     my $content_ref = get_page_with_curl($cgi_url);
1052     my $status_code = get_status_code($content_ref);
1053
1054     if (200 != $status_code) {
1055
1056         my $log_message = "Failed to fetch Privoxy CGI Page. " .
1057                           "Received status code ". $status_code .
1058                           " while only 200 is acceptable.";
1059
1060         if (cli_option_is_set('fuzzer-feeding')) {
1061
1062             $log_message .= " Ignored due to fuzzer feeding.";
1063             l(LL_SOFT_ERROR, $log_message)
1064
1065         } else {
1066
1067             l(LL_ERROR, $log_message);
1068
1069         }
1070     }
1071
1072     return $content_ref;
1073 }
1074
1075 sub get_show_request_with_curl ($) {
1076
1077     our $privoxy_cgi_url;
1078     my $test_ref = shift;
1079     my %test = %{$test_ref};
1080
1081     my $curl_parameters = ' ';
1082
1083     # Enable the action to test
1084     $curl_parameters .= '-H \'X-Privoxy-Control: ' . $test{'tag'} . '\' ';
1085     # The header to filter
1086     $curl_parameters .= '-H \'' . $test{'data'} . '\' ';
1087
1088     $curl_parameters .= ' ';
1089     $curl_parameters .= $privoxy_cgi_url;
1090     $curl_parameters .= 'show-request';
1091
1092     return get_cgi_page_or_else($curl_parameters);
1093 }
1094
1095
1096 sub get_head_with_curl ($) {
1097
1098     our $fellatio_url = FELLATIO_URL;
1099     my $test_ref = shift;
1100     my %test = %{$test_ref};
1101
1102     my $curl_parameters = ' ';
1103
1104     # Enable the action to test
1105     $curl_parameters .= '-H \'X-Privoxy-Control: ' . $test{'tag'} . '\' ';
1106     # The header to filter
1107     $curl_parameters .= '-H \'X-Gimme-Head-With: ' . $test{'data'} . '\' ';
1108     $curl_parameters .= '--head ';
1109
1110     $curl_parameters .= ' ';
1111     $curl_parameters .= $fellatio_url;
1112
1113     return get_page_with_curl($curl_parameters);
1114 }
1115
1116
1117 sub get_page_with_curl ($) {
1118
1119     my $parameters = shift;
1120     my @buffer;
1121     my $curl_line = CURL;
1122     my $retries_left = get_cli_option('retries') + 1;
1123     my $failure_reason;
1124
1125     if (cli_option_is_set('privoxy-address')) {
1126         $curl_line .= ' --proxy ' . get_cli_option('privoxy-address');
1127     }
1128
1129     # We want to see the HTTP status code
1130     $curl_line .= " --include ";
1131     # Let Privoxy emit two log messages less.
1132     $curl_line .= ' -H \'Proxy-Connection:\' ' unless $parameters =~ /Proxy-Connection:/;
1133     $curl_line .= ' -H \'Connection: close\' ' unless $parameters =~ /Connection:/;
1134     # We don't care about fetch statistic.
1135     $curl_line .= " -s ";
1136     # We do care about the failure reason if any.
1137     $curl_line .= " -S ";
1138     # We want to advertise ourselves
1139     $curl_line .= " --user-agent '" . PRT_VERSION . "' ";
1140     # We aren't too patient
1141     $curl_line .= " --max-time '" . get_cli_option('max-time') . "' ";
1142
1143     $curl_line .= $parameters;
1144     # XXX: still necessary?
1145     $curl_line .= ' 2>&1';
1146
1147     l(LL_PAGE_FETCHING, "Executing: " . $curl_line);
1148
1149     do {
1150         @buffer = `$curl_line`;
1151
1152         if ($?) {
1153             $failure_reason = array_as_string(\@buffer);
1154             chomp $failure_reason;
1155             l(LL_SOFT_ERROR, "Fetch failure: '" . $failure_reason . $! ."'");
1156         }
1157     } while ($? && --$retries_left);
1158
1159     unless ($retries_left) {
1160         l(LL_ERROR,
1161           "Running curl failed " . get_cli_option('retries') .
1162           " times in a row. Last error: '" . $failure_reason . "'.");
1163     }
1164
1165     return \@buffer;
1166 }
1167
1168
1169 ############################################################################
1170 #
1171 # Log functions
1172 #
1173 ############################################################################
1174
1175 sub array_as_string ($) {
1176     my $array_ref = shift;
1177     my $string = '';
1178
1179     foreach (@{$array_ref}) {
1180         $string .= $_;
1181     }
1182
1183     return $string;
1184 }
1185
1186
1187 sub show_test ($) {
1188     my $test_ref = shift;
1189     log_message('Test is:' . test_content_as_string($test_ref));
1190 }
1191
1192 # Conditional log
1193 sub l ($$) {
1194     our $log_level;
1195     my $this_level = shift;
1196     my $message = shift;
1197
1198     return unless ($log_level & $this_level);
1199
1200     if (LL_ERROR & $this_level) {
1201         $message = 'Oh noes. ' . $message . ' Fatal error. Exiting.';
1202     }
1203
1204     log_message($message);
1205
1206     if (LL_ERROR & $this_level) {
1207         exit;
1208     }
1209 }
1210
1211 sub log_message ($) {
1212
1213     my $message = shift;
1214
1215     our $logfile;
1216     our $no_logging;
1217     our $leading_log_date;
1218     our $leading_log_time;
1219
1220     my $time_stamp = '';
1221     my ( $sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst ) = localtime time;
1222
1223     if ($leading_log_date || $leading_log_time) {
1224
1225         if ($leading_log_date) {
1226             $year += 1900;
1227             $mon  += 1;
1228             $time_stamp = sprintf("%i/%.2i/%.2i", $year, $mon, $mday);
1229         }
1230
1231         if ($leading_log_time) {
1232             $time_stamp .= ' ' if $leading_log_date;
1233             $time_stamp.= sprintf("%.2i:%.2i:%.2i", $hour, $min, $sec);
1234         }
1235
1236         $message = $time_stamp . ": " . $message;
1237     }
1238
1239
1240     printf(STDERR "%s\n", $message);
1241
1242 }
1243
1244 sub log_result ($$) {
1245
1246     our $verbose_test_description;
1247     our $filtered_request;
1248
1249     my $test_ref = shift;
1250     my $result = shift;
1251     my $number = shift;
1252
1253     my %test = %{$test_ref};
1254     my $message = '';
1255
1256     $message .= interpret_result($result);
1257     $message .= " for test ";
1258     $message .= $number;
1259     $message .= '/';
1260     $message .= $test{'number'};
1261     $message .= '/';
1262     $message .= $test{'section-id'};
1263     $message .= '/';
1264     $message .= $test{'regression-test-id'};
1265     $message .= '.';
1266
1267     if ($verbose_test_description) {
1268
1269         if ($test{'type'} == CLIENT_HEADER_TEST) {
1270
1271             $message .= ' Header ';
1272             $message .= quote($test{'data'});
1273             $message .= ' and tag ';
1274             $message .= quote($test{'tag'});
1275
1276         } elsif ($test{'type'} == SERVER_HEADER_TEST) {
1277
1278             $message .= ' Request Header ';
1279             $message .= quote($test{'data'});
1280             $message .= ' and tag ';
1281             $message .= quote($test{'tag'});
1282
1283         } elsif ($test{'type'} == DUMB_FETCH_TEST) {
1284
1285             $message .= ' URL ';
1286             $message .= quote($test{'data'});
1287             $message .= ' and expected status code ';
1288             $message .= quote($test{'expected-status-code'});
1289
1290         } elsif ($test{'type'} == TRUSTED_CGI_REQUEST) {
1291
1292             $message .= ' CGI URL ';
1293             $message .= quote($test{'data'});
1294             $message .= ' and expected status code ';
1295             $message .= quote($test{'expected-status-code'});
1296
1297         } elsif ($test{'type'} == METHOD_TEST) {
1298
1299             $message .= ' HTTP method ';
1300             $message .= quote($test{'data'});
1301             $message .= ' and expected status code ';
1302             $message .= quote($test{'expected-status-code'});
1303
1304         } elsif ($test{'type'} == BLOCK_TEST) {
1305
1306             $message .= ' Supposedly-blocked URL: ';
1307             $message .= quote($test{'data'});
1308
1309         } elsif ($test{'type'} == STICKY_ACTIONS_TEST) {
1310
1311             $message .= ' Sticky Actions: ';
1312             $message .= quote($test{'sticky-actions'});
1313             $message .= ' and URL: ';
1314             $message .= quote($test{'data'});
1315
1316         } else {
1317
1318             die "Incomplete support for test type " . $test{'type'} .  " detected.";
1319
1320         }
1321     }
1322
1323     log_message($message) unless ($result && cli_option_is_set('silent'));
1324 }
1325
1326 sub quote ($) {
1327     my $s = shift;
1328     return '\'' . $s . '\'';
1329 }
1330
1331 sub print_version () {
1332     printf PRT_VERSION . "\n" . 'Copyright (C) 2007-2008 Fabian Keil <fk@fabiankeil.de>' . "\n";
1333 }
1334
1335 sub help () {
1336
1337     our %cli_options;
1338
1339     print_version();
1340
1341     print << "    EOF"
1342
1343 Options and their default values if they have any:
1344     [--debug $cli_options{'debug'}]
1345     [--fuzzer-feeding]
1346     [--help]
1347     [--level]
1348     [--loops $cli_options{'loops'}]
1349     [--max-level $cli_options{'max-level'}]
1350     [--max-time $cli_options{'max-time'}]
1351     [--min-level $cli_options{'min-level'}]
1352     [--privoxy-address]
1353     [--retries $cli_options{'retries'}]
1354     [--silent]
1355     [--version]
1356 see "perldoc $0" for more information
1357     EOF
1358     ;
1359     exit(0);
1360 }
1361
1362 sub init_cli_options () {
1363
1364     our %cli_options;
1365     our $log_level;
1366
1367     $cli_options{'min-level'} = CLI_MIN_LEVEL;
1368     $cli_options{'max-level'} = CLI_MAX_LEVEL;
1369     $cli_options{'debug'}  = $log_level;
1370     $cli_options{'loops'}  = CLI_LOOPS;
1371     $cli_options{'max-time'}  = CLI_MAX_TIME;
1372     $cli_options{'retries'}  = CLI_RETRIES;
1373 }
1374
1375 sub parse_cli_options () {
1376
1377     our %cli_options;
1378     our $log_level;
1379
1380     init_cli_options();
1381
1382     GetOptions (
1383                 'debug=s' => \$cli_options{'debug'},
1384                 'help'     => sub { help },
1385                 'silent' => \$cli_options{'silent'},
1386                 'min-level=s' => \$cli_options{'min-level'},
1387                 'max-level=s' => \$cli_options{'max-level'},
1388                 'privoxy-address=s' => \$cli_options{'privoxy-address'},
1389                 'level=s' => \$cli_options{'level'},
1390                 'loops=s' => \$cli_options{'loops'},
1391                 'test-number=s' => \$cli_options{'test-number'},
1392                 'fuzzer-feeding' => \$cli_options{'fuzzer-feeding'},
1393                 'retries=s' => \$cli_options{'retries'},
1394                 'max-time=s' => \$cli_options{'max-time'},
1395                 'version'  => sub { print_version && exit(0) }
1396     );
1397     $log_level |= $cli_options{'debug'};
1398 }
1399
1400 sub cli_option_is_set ($) {
1401
1402     our %cli_options;
1403     my $cli_option = shift;
1404
1405     return defined $cli_options{$cli_option};
1406 }
1407
1408 sub get_cli_option ($) {
1409
1410     our %cli_options;
1411     my $cli_option = shift;
1412
1413     die "Unknown CLI option: $cli_option" unless defined $cli_options{$cli_option};
1414
1415     return $cli_options{$cli_option};
1416 }
1417
1418 sub main () {
1419
1420     init_our_variables();
1421     parse_cli_options();
1422     check_for_curl();
1423     load_regressions_tests();
1424     execute_regression_tests();
1425 }
1426
1427 main();
1428
1429 =head1 NAME
1430
1431 B<privoxy-regression-test> - A regression test "framework" for Privoxy.
1432
1433 =head1 SYNOPSIS
1434
1435 B<privoxy-regression-test> [B<--debug bitmask>] [B<--fuzzer-feeding>] [B<--help>]
1436 [B<--level level>] [B<--loops count>] [B<--max-level max-level>]
1437 [B<--max-time max-time>] [B<--min-level min-level>] B<--privoxy-address proxy-address>
1438 [B<--retries retries>] [B<--silent>] [B<--version>]
1439
1440 =head1 DESCRIPTION
1441
1442 Privoxy-Regression-Test is supposed to one day become
1443 a regression test suite for Privoxy. It's not quite there
1444 yet, however, and can currently only test header actions,
1445 check the returned status code for requests to arbitrary
1446 URLs and verify which actions are applied to them.
1447
1448 Client header actions are tested by requesting
1449 B<http://p.p/show-request> and checking whether
1450 or not Privoxy modified the original request as expected.
1451
1452 The original request contains both the header the action-to-be-tested
1453 acts upon and an additional tagger-triggering header that enables
1454 the action to test.
1455
1456 Applied actions are checked through B<http://p.p/show-url-info>.
1457
1458 =head1 CONFIGURATION FILE SYNTAX
1459
1460 Privoxy-Regression-Test's configuration is embedded in
1461 Privoxy action files and loaded through Privoxy's web interface.
1462
1463 It makes testing a Privoxy version running on a remote system easier
1464 and should prevent you from updating your tests without updating Privoxy's
1465 configuration accordingly.
1466
1467 A client-header-action test section looks like this:
1468
1469     # Set Header    = Referer: http://www.example.org.zwiebelsuppe.exit/
1470     # Expect Header = Referer: http://www.example.org/
1471     {+client-header-filter{hide-tor-exit-notation} -hide-referer}
1472     TAG:^client-header-filter\{hide-tor-exit-notation\}$
1473
1474 The example above causes Privoxy-Regression-Test to set
1475 the header B<Referer: http://www.example.org.zwiebelsuppe.exit/>
1476 and to expect it to be modified to
1477 B<Referer: http://www.example.org/>.
1478
1479 When testing this section, Privoxy-Regression-Test will set the header
1480 B<X-Privoxy-Control: client-header-filter{hide-tor-exit-notation}>
1481 causing the B<privoxy-control> tagger to create the tag
1482 B<client-header-filter{hide-tor-exit-notation}> which will finally
1483 cause Privoxy to enable the action section.
1484
1485 Note that the actions itself are only used by Privoxy,
1486 Privoxy-Regression-Test ignores them and will be happy
1487 as long as the expectations are satisfied.
1488
1489 A fetch test looks like this:
1490
1491     # Fetch Test = http://p.p/user-manual
1492     # Expect Status Code = 302
1493
1494 It tells Privoxy-Regression-Test to request B<http://p.p/user-manual>
1495 and to expect a response with the HTTP status code B<302>. Obviously that's
1496 not a very thorough test and mainly useful to get some code coverage
1497 for Valgrind or to verify that the templates are installed correctly.
1498
1499 If you want to test CGI pages that require a trusted
1500 referer, you can use:
1501
1502     # Trusted CGI Request = http://p.p/edit-actions
1503
1504 It works like ordinary fetch tests, but sets the referer
1505 header to a trusted value.
1506
1507 If no explicit status code expectation is set, B<200> is used.
1508
1509 To verify that a URL is blocked, use:
1510
1511     # Blocked URL = http://www.example.com/blocked
1512
1513 To verify that a specific set of actions is applied to an URL, use:
1514
1515     # Sticky Actions = +block{foo} +handle-as-empty-document -handle-as-image
1516     # URL = http://www.example.org/my-first-url
1517
1518 The sticky actions will be checked for all URLs below it
1519 until the next sticky actions directive.
1520
1521 =head1 TEST LEVELS
1522
1523 All tests have test levels to let the user
1524 control which ones to execute (see I<OPTIONS> below).
1525 Test levels are either set with the B<Level> directive,
1526 or implicitly through the test type.
1527
1528 Block tests default to level 7, fetch tests to level 6,
1529 "Sticky Actions" tests default to level 5, tests for trusted CGI
1530 requests to level 3 and client-header-action tests to level 1.
1531
1532 =head1 OPTIONS
1533
1534 B<--debug bitmask> Add the bitmask provided as integer
1535 to the debug settings.
1536
1537 B<--fuzzer-feeding> Ignore some errors that would otherwise
1538 cause Privoxy-Regression-Test to abort the test because
1539 they shouldn't happen in normal operation. This option is
1540 intended to be used if Privoxy-Regression-Test is only
1541 used to feed a fuzzer in which case there's a high chance
1542 that Privoxy gets an invalid request and returns an error
1543 message.
1544
1545 B<--help> Shows available command line options.
1546
1547 B<--level level> Only execute tests with the specified B<level>.
1548
1549 B<--loop count> Loop through the regression tests B<count> times.
1550 Useful to feed a fuzzer, or when doing stress tests with
1551 several Privoxy-Regression-Test instances running at the same
1552 time.
1553
1554 B<--max-level max-level> Only execute tests with a B<level>
1555 below or equal to the numerical B<max-level>.
1556
1557 B<--max-time max-time> Give Privoxy B<max-time> seconds
1558 to return data. Increasing the default may make sense when
1559 Privoxy is run through Valgrind, decreasing the default may
1560 make sense when Privoxy-Regression-Test is used to feed
1561 a fuzzer.
1562
1563 B<--min-level min-level> Only execute tests with a B<level>
1564 above or equal to the numerical B<min-level>.
1565
1566 B<--privoxy-address proxy-address> Privoxy's listening address.
1567 If it's not set, the value of the environment variable http_proxy
1568 will be used. B<proxy-address> has to be specified in http_proxy
1569 syntax.
1570
1571 B<--retries retries> Retry B<retries> times.
1572
1573 B<--silent> Don't log succesful test runs.
1574
1575 B<--version> Print version and exit.
1576
1577 The second dash is optional, options can be shortened,
1578 as long as there are no ambiguities.
1579
1580 =head1 PRIVOXY CONFIGURATION
1581
1582 Privoxy-Regression-Test is shipped with B<regression-tests.action>
1583 which aims to test all official client-header modifying actions
1584 and can be used to verify that the templates and the user manual
1585 files are installed correctly.
1586
1587 To use it, it has to be copied in Privoxy's configuration
1588 directory, and afterwards referenced in Privoxy's configuration
1589 file with the line:
1590
1591     actionsfile regression-tests.action
1592
1593 In general, its tests are supposed to work without changing
1594 any other action files, unless you already added lots of
1595 taggers yourself. If you are using taggers that cause problems,
1596 you might have to temporary disable them for Privoxy's CGI pages.
1597
1598 Some of the regression tests rely on Privoxy features that
1599 may be disabled in your configuration. Tests with a level below
1600 7 are supposed to work with all Privoxy configurations (provided
1601 you didn't build with FEATURE_GRACEFUL_TERMINATION).
1602
1603 Tests with level 9 require Privoxy to deliver the User Manual,
1604 tests with level 12 require the CGI editor to be enabled.
1605
1606 =head1 CAVEATS
1607
1608 Expect the configuration file syntax to change with future releases.
1609
1610 =head1 LIMITATIONS
1611
1612 As Privoxy's B<show-request> page only shows client headers,
1613 Privoxy-Regression-Test can't use it to test Privoxy actions
1614 that modify server headers.
1615
1616 As Privoxy-Regression-Test relies on Privoxy's tag feature to
1617 control the actions to test, it currently only works with
1618 Privoxy 3.0.7 or later.
1619
1620 At the moment Privoxy-Regression-Test fetches Privoxy's
1621 configuration page through I<curl>(1), therefore you have to
1622 have I<curl> installed, otherwise you won't be able to run
1623 Privoxy-Regression-Test in a meaningful way.
1624
1625 =head1 SEE ALSO
1626
1627 privoxy(1) curl(1)
1628
1629 =head1 AUTHOR
1630
1631 Fabian Keil <fk@fabiankeil.de>
1632
1633 =cut