.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "Test::HTTP::LocalServer 3pm"
.TH Test::HTTP::LocalServer 3pm "2021-10-29" "perl v5.32.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"
Test::HTTP::LocalServer \- spawn a local HTTP server for testing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use HTTP::Tiny;
\&  my $server = Test::HTTP::LocalServer\->spawn(
\&      request_pause => 1, # wait one second before accepting the next request
\&  );
\&
\&  my $res = HTTP::Tiny\->new\->get( $server\->url );
\&  print $res\->{content};
\&
\&  $server\->stop;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a tiny web server suitable for running \*(L"live\*(R" tests
of \s-1HTTP\s0 clients against it. It also takes care of cleaning \f(CW%ENV\fR from settings
that influence the use of a local proxy etc.
.PP
Use this web server if you write an \s-1HTTP\s0 client and want to exercise its
behaviour in your test suite without talking to the outside world.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """Test::HTTP::LocalServer\->spawn %ARGS"""
.el .SS "\f(CWTest::HTTP::LocalServer\->spawn %ARGS\fP"
.IX Subsection "Test::HTTP::LocalServer->spawn %ARGS"
.Vb 1
\&  my $server = Test::HTTP::LocalServer\->spawn;
.Ve
.PP
This spawns a new \s-1HTTP\s0 server. The server will stay running until
.PP
.Vb 1
\&  $server\->stop
.Ve
.PP
is called. Ideally, you explicitly call \f(CW\*(C`\->stop\*(C'\fR or use
.PP
.Vb 1
\&  undef $server
.Ve
.PP
before the main program ends so that the program exit code reflects the
real exit code and not the chlid exit code.
.PP
Valid arguments are :
.IP "\(bu" 4
\&\f(CW\*(C`html =>\*(C'\fR scalar containing the page to be served
.Sp
If this is not specified, an informative default page will be used.
.IP "\(bu" 4
\&\f(CW\*(C`request_pause =>\*(C'\fR number of seconds to sleep before accepting the next
request
.Sp
If your system is slow or needs to wait some time before a socket connection
is ready again, use this parameter to make the server wait a bit before
handling the next connection.
.IP "\(bu" 4
\&\f(CW\*(C`file =>\*(C'\fR filename containing the page to be served
.IP "\(bu" 4
\&\f(CW\*(C`debug => 1\*(C'\fR to make the spawned server output debug information
.IP "\(bu" 4
\&\f(CW\*(C`eval =>\*(C'\fR string that will get evaluated per request in the server
.Sp
Try to avoid characters that are special to the shell, especially quotes.
A good idea for a slow server would be
.Sp
.Vb 1
\&  eval => sleep+10
.Ve
.PP
All served \s-1HTML\s0 will have the first \f(CW%s\fR replaced by the current location.
.PP
The following entries will be removed from \f(CW%ENV\fR when making a request:
.PP
.Vb 9
\&    HTTP_PROXY
\&    http_proxy
\&    HTTP_PROXY_ALL
\&    http_proxy_all
\&    HTTPS_PROXY
\&    https_proxy
\&    CGI_HTTP_PROXY
\&    ALL_PROXY
\&    all_proxy
.Ve
.ie n .SS """$server\->port"""
.el .SS "\f(CW$server\->port\fP"
.IX Subsection "$server->port"
This returns the port of the current server. As new instances
will most likely run under a different port, this is convenient
if you need to compare results from two runs.
.ie n .SS """$server\->url"""
.el .SS "\f(CW$server\->url\fP"
.IX Subsection "$server->url"
This returns the \s-1URI\s0 where you can contact the server. This url
is valid until the \f(CW$server\fR goes out of scope or you call
.PP
.Vb 1
\&  $server\->stop;
.Ve
.PP
The returned object is a copy that you can modify at your leisure.
.ie n .SS """$server\->server_url"""
.el .SS "\f(CW$server\->server_url\fP"
.IX Subsection "$server->server_url"
This returns the \s-1URI\s0 object of the server \s-1URL.\s0 Use \*(L"$server\->url\*(R" instead.
Use this object if you want to modify the hostname or other properties of the
server object.
.PP
Consider this basically an emergency accessor. In about every case,
using \f(CW\*(C`\->url()\*(C'\fR does what you want.
.ie n .SS """$server\->stop"""
.el .SS "\f(CW$server\->stop\fP"
.IX Subsection "$server->stop"
This stops the server process by requesting a special
url.
.ie n .SS """$server\->kill"""
.el .SS "\f(CW$server\->kill\fP"
.IX Subsection "$server->kill"
This kills the server process via \f(CW\*(C`kill\*(C'\fR. The log
cannot be retrieved then.
.ie n .SS """$server\->get_log"""
.el .SS "\f(CW$server\->get_log\fP"
.IX Subsection "$server->get_log"
This returns the
output of the server process. This output will be a list of
all requests made to the server concatenated together
as a string.
.ie n .SS """$server\->local"""
.el .SS "\f(CW$server\->local\fP"
.IX Subsection "$server->local"
.Vb 2
\&  my $url = $server\->local(\*(Aqfoo.html\*(Aq);
\&  # file:///.../foo.html
.Ve
.PP
Returns an \s-1URL\s0 for a local file which will be read and served
by the webserver. The filename must
be a relative filename relative to the location of the current
program.
.SH "URLs implemented by the server"
.IX Header "URLs implemented by the server"
.ie n .SS "arbitrary content ""$server\->content($html)"""
.el .SS "arbitrary content \f(CW$server\->content($html)\fP"
.IX Subsection "arbitrary content $server->content($html)"
.Vb 3
\&  $server\->content(<<\*(AqHTML\*(Aq);
\&      <script>alert("Hello World");</script>
\&  HTML
.Ve
.PP
The \s-1URL\s0 will contain the \s-1HTML\s0 as supplied. This is convenient for supplying
Javascript or special \s-1URL\s0 to your user agent.
.ie n .SS "download ""$server\->download($name)"""
.el .SS "download \f(CW$server\->download($name)\fP"
.IX Subsection "download $server->download($name)"
This \s-1URL\s0 will send a file with a \f(CW\*(C`Content\-Disposition\*(C'\fR header and indicate
the suggested filename as passed in.
.ie n .SS "302 redirect ""$server\->redirect($target)"""
.el .SS "302 redirect \f(CW$server\->redirect($target)\fP"
.IX Subsection "302 redirect $server->redirect($target)"
This \s-1URL\s0 will issue a redirect to \f(CW$target\fR. No special care is taken
towards URL-decoding \f(CW$target\fR as not to complicate the server code.
You need to be wary about issuing requests with escaped \s-1URL\s0 parameters.
.ie n .SS "401 basic authentication challenge ""$server\->basic_auth($user, $pass)"""
.el .SS "401 basic authentication challenge \f(CW$server\->basic_auth($user, $pass)\fP"
.IX Subsection "401 basic authentication challenge $server->basic_auth($user, $pass)"
This \s-1URL\s0 will issue a 401 basic authentication challenge. The expected user
and password are encoded in the \s-1URL.\s0
.PP
.Vb 5
\&    my $challenge_url = $server\->basic_auth(\*(Aqfoo\*(Aq,\*(Aqsecret\*(Aq);
\&    my $wrong_pw = URI\->new( $challenge_url );
\&    $wrong_pw\->userinfo(\*(Aqfoo:hunter2\*(Aq);
\&    $res = HTTP::Tiny\->new\->get($wrong_pw);
\&    is $res\->{status}, 401, "We get the challenge with a wrong user/password";
.Ve
.ie n .SS "404 error ""$server\->error_notfound($target)"""
.el .SS "404 error \f(CW$server\->error_notfound($target)\fP"
.IX Subsection "404 error $server->error_notfound($target)"
This \s-1URL\s0 will response with status code 404.
.ie n .SS "Timeout ""$server\->error_timeout($seconds)"""
.el .SS "Timeout \f(CW$server\->error_timeout($seconds)\fP"
.IX Subsection "Timeout $server->error_timeout($seconds)"
This \s-1URL\s0 will send a 599 error after \f(CW$seconds\fR seconds.
.ie n .SS "Timeout+close ""$server\->error_close($seconds)"""
.el .SS "Timeout+close \f(CW$server\->error_close($seconds)\fP"
.IX Subsection "Timeout+close $server->error_close($seconds)"
This \s-1URL\s0 will send nothing and close the connection after \f(CW$seconds\fR seconds.
.ie n .SS "Error in response content ""$server\->error_after_headers"""
.el .SS "Error in response content \f(CW$server\->error_after_headers\fP"
.IX Subsection "Error in response content $server->error_after_headers"
This \s-1URL\s0 will send headers for a successful response but will close the
socket with an error after 2 blocks of 16 spaces have been sent.
.ie n .SS "Chunked response ""$server\->chunked"""
.el .SS "Chunked response \f(CW$server\->chunked\fP"
.IX Subsection "Chunked response $server->chunked"
This \s-1URL\s0 will return 5 blocks of 16 spaces at a rate of one block per second
in a chunked response.
.ie n .SS "Surprisingly large bzip2 encoded response ""$server\->bzip2"""
.el .SS "Surprisingly large bzip2 encoded response \f(CW$server\->bzip2\fP"
.IX Subsection "Surprisingly large bzip2 encoded response $server->bzip2"
This \s-1URL\s0 will return a short \s-1HTTP\s0 response that expands to 16M body.
.ie n .SS "Surprisingly large gzip encoded response ""$server\->gzip"""
.el .SS "Surprisingly large gzip encoded response \f(CW$server\->gzip\fP"
.IX Subsection "Surprisingly large gzip encoded response $server->gzip"
This \s-1URL\s0 will return a short \s-1HTTP\s0 response that expands to 16M body.
.SS "Other URLs"
.IX Subsection "Other URLs"
All other URLs will echo back the cookies and query parameters.
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
Copyright (C) 2003\-2021 Max Maischein
.SH "AUTHOR"
.IX Header "AUTHOR"
Max Maischein, <corion@cpan.org>
.PP
Please contact me if you find bugs or otherwise improve the module. More tests
are also very welcome !
.SH "SEE ALSO"
.IX Header "SEE ALSO"
WWW::Mechanize,WWW::Mechanize::Shell,WWW::Mechanize::Firefox