NAME
Test::HTTP::LocalServer - spawn a local HTTP server for testing
SYNOPSIS
use HTTP::Tiny;
my $server = Test::HTTP::LocalServer->spawn;
my $res = HTTP::Tiny->new->get( $server->url );
print $res->{content};
$server->stop;
DESCRIPTION
This module implements a tiny web server suitable for running "live" tests
of HTTP clients against it. It also takes care of cleaning %ENV
from settings
that influence the use of a local proxy etc.
Use this web server if you write an HTTP client and want to exercise its behaviour in your test suite without talking to the outside world.
METHODS
Test::HTTP::LocalServer->spawn %ARGS
my $server = Test::HTTP::LocalServer->spawn;
This spawns a new HTTP server. The server will stay running until $server->stop is called.
Valid arguments are :
-
html =>
scalar containing the page to be served -
file =>
filename containing the page to be served -
debug => 1
to make the spawned server output debug information -
eval =>
string that will get evaluated per request in the serverTry to avoid characters that are special to the shell, especially quotes. A good idea for a slow server would be
eval => sleep+10
All served HTML will have the first %s replaced by the current location.
The following entries will be removed from %ENV
when making a request:
HTTP_PROXY
http_proxy
HTTP_PROXY_ALL
http_proxy_all
HTTPS_PROXY
https_proxy
CGI_HTTP_PROXY
ALL_PROXY
all_proxy
$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.
$server->url
This returns the URI where you can contact the server. This url
is valid until the $server
goes out of scope or you call
$server->stop;
The returned object is a copy that you can modify at your leisure.
$server->server_url
This returns the URI object of the server URL. Use "$server-"url> instead. Use this object if you want to modify the hostname or other properties of the server object.
Consider this basically an emergency accessor. In about every case,
using ->url()
does what you want.
$server->stop
This stops the server process by requesting a special url.
$server->kill
This kills the server process via kill
. The log
cannot be retrieved then.
$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.
$server->local
my $url = $server->local('foo.html');
# file:///.../foo.html
Returns an URL 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.
URLs implemented by the server
$server->content($html)
arbitrary content $server->content(<<'HTML');
<script>alert("Hello World");</script>
HTML
The URL will contain the HTML as supplied. This is convenient for supplying Javascript or special URL to your user agent.
$server->download($name)
download This URL will send a file with a Content-Disposition
header and indicate
the suggested filename as passed in.
$server->redirect($target)
302 redirect This URL will issue a redirect to $target
. No special care is taken
towards URL-decoding $target
as not to complicate the server code.
You need to be wary about issuing requests with escaped URL parameters.
$server->basic_auth($user, $pass)
401 basic authentication challenge This URL will issue a 401 basic authentication challenge. The expected user and password are encoded in the URL.
my $challenge_url = $server->basic_auth('foo','secret');
my $wrong_pw = URI->new( $challenge_url );
$wrong_pw->userinfo('foo:hunter2');
$res = HTTP::Tiny->new->get($wrong_pw);
is $res->{status}, 401, "We get the challenge with a wrong user/password";
$server->error_notfound($target)
404 error This URL will response with status code 404.
$server->error_timeout($seconds)
Timeout This URL will send a 599 error after $seconds
seconds.
$server->error_close($seconds)
Timeout+close This URL will send nothing and close the connection after $seconds
seconds.
$server->error_after_headers
Error in response content This URL will send headers for a successful response but will close the socket with an error after 2 blocks of 16 spaces have been sent.
$server->chunked
Chunked response This URL will return 5 blocks of 16 spaces at a rate of one block per second in a chunked response.
$server->bzip2
Surprisingly large bzip2 encoded response This URL will return a short HTTP response that expands to 16M body.
$server->gzip
Surprisingly large gzip encoded response This URL will return a short HTTP response that expands to 16M body.
Other URLs
All other URLs will echo back the cookies and query parameters.
EXPORT
None by default.
COPYRIGHT AND LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Copyright (C) 2003-2019 Max Maischein
AUTHOR
Max Maischein, [email protected]
Please contact me if you find bugs or otherwise improve the module. More tests are also very welcome !
SEE ALSO
WWW::Mechanize,WWW::Mechanize::Shell,WWW::Mechanize::Firefox