Test::...lServer(3pm)

💖 Test::HTTP::LocalServer — bestie, let's spin up a whole local HTTP server 💖

okay so this page is from the Test::...lServer(3pm) manual, and it's about Test::HTTP::LocalServer — a lil web server you spawn for testing. no cap. 🦋

---

✨ NAME ✨

Test::HTTP::LocalServer — spawn a local HTTP server for testing. that's it, that's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

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;

see how easy that was?? spawn, poke it, stop it. iconic behavior fr fr 💅

---

🎀 DESCRIPTION 🎀

So this module implements a tiny web server — like, the smallest possible — and it's absolutely perfect for running "live" tests of HTTP clients against it. It also handles cleaning %ENV of all those settings that mess with your local proxy and stuff, which, honestly, thank you, that's so thoughtful of it. 😭

Use this web server if you're writing an HTTP client and you want to exercise its behaviour in your test suite without talking to the outside world. no internet, no drama, just you and your lil local server. 🏠✨

---

🧚 METHODS 🧚

Test::HTTP::LocalServer->spawn %ARGS

my $server = Test::HTTP::LocalServer->spawn;

This spawns a brand new HTTP server. She will stay running until

$server->stop

gets called. And listen — ideally you explicitly call ->stop or use

undef $server

before the main program ends, so that the program exit code reflects the real exit code and not the child exit code. don't let your tests gaslight you with a fake exit code bestie, clean up properly. 🧹💖

The valid arguments are:

• html => scalar containing the page to be served — if this isn't specified, an informative default page gets used instead. free content, no notes. 🎁
• request_pause => number of seconds to sleep before accepting the next request — 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. it's literally just ✨ patience ✨
• 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 server — try 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. that's the little placeholder magic right there ✨

The following entries get 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

bye bye proxy settings, we don't know her 💀

---

$server->port

This returns the port of the current server. Since new instances will most likely run under a different port, this is convenient if you need to compare results from two runs. lowkey so useful. 🔢

---

$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. it's yours, customize it, go off. 🎨

---

$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. like, this one is the "break glass in case of emergency" option 🚨 — ->url() is your girl, trust her.

---

$server->stop

This stops the server process by requesting a special url. polite. courteous. she knocks on the door and asks nicely. 🚪✨

---

$server->kill

This kills the server process via kill. The log cannot be retrieved then. so like, dramatic exit, but you lose the receipts. 💀

---

$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. the whole story, front to back, one 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. no absolute paths, bestie, relative only, i don't make the rules. 🙈

---

🌈 URLs implemented by the server 🌈

arbitrary content $server->content($html)

$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. bring your own content, she'll serve it. 🍓

download $server->download($name)

This URL will send a file with a Content-Disposition header and indicate the suggested filename as passed in. it's giving "here's your file, take it" 📥

302 redirect $server->redirect($target)

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. so like, heads up, no decoding happening here, be careful with those escaped params. ⚠️

401 basic authentication challenge $server->basic_auth($user, $pass)

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";

wrong password gang rise up 🔐

404 error $server->error_notfound($target)

This URL will response with status code 404. the classic. the legend. she's not here bestie. 👻

Timeout $server->error_timeout($seconds)

This URL will send a 599 error after $seconds seconds. wait for it… wait for it… ⏳

Timeout+close $server->error_close($seconds)

This URL will send nothing and close the connection after $seconds seconds. ghosting, but on purpose. 💀

Error in response content $server->error_after_headers

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. so close! she got the headers out and then just… gave up. 😭

Chunked response $server->chunked

This URL will return 5 blocks of 16 spaces at a rate of one block per second in a chunked response. one block per second, very demure, very mindful, very cutesy. 🎀

Surprisingly large bzip2 encoded response $server->bzip2

This URL will return a short HTTP response that expands to 16M body. SURPRISE. 🎉

Surprisingly large gzip encoded response $server->gzip

This URL will return a short HTTP response that expands to 16M body. same energy, different compression. 🔥

Other URLs

All other URLs will echo back the cookies and query parameters. she's a mirror bestie, she reflects you back at yourself ✨

---

🫶 EXPORT 🫶

None by default. nothing. zero. nada. you get what you ask for and that's it 💅

---

👑 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-2024 Max Maischein

---

🌟 AUTHOR 🌟

Max Maischein, <corion@cpan.org>

Please contact me if you find bugs or otherwise improve the module. More tests are also very welcome! bugs? improvements? tests?? slide into the inbox, all of it is appreciated fr fr 🫶💖

---

🔥 SEE ALSO 🔥

WWW::Mechanize, WWW::Mechanize::Shell, WWW::Mechanize::Firefox

---

okay that's the whole page bestie, go write some tests 💖

this was the Test::...lServer(3pm) page — perl v5.38.2, dated 2024-03-09 — mwah, thanks for reading, you ate that 🎀✨💅