Test::...::HTTPD(3pm)

💖 NAME 💖

Test::Fake::HTTPD — it's a fake HTTP server, bestie. Like, a whole lil server that exists purely so your tests have somewhere to play. No cap. 🎀

---

✨ SYNOPSIS ✨

Okay so there are two ways to do this. Two vibes. Pick your fighter. 💅

🌸 DSL-style

use Test::Fake::HTTPD;

my $httpd = run_http_server {
    my $req = shift;
    # ...

    # 1. HTTP::Response ok
    return $http_response;
    # 2. Plack::Response ok
    return $plack_response;
    # 3. PSGI response ok
    return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello World' ] ];
};

printf "Listening on address:port %s\n", $httpd->host_port;
# or
printf "Listening on address %s port %s\n", $httpd->host, $httpd->port;

# access to fake HTTP server
use LWP::UserAgent;
my $res = LWP::UserAgent->new->get($httpd->endpoint); # "http://127.0.0.1:{port}"

# Stop http server automatically at destruction time.

🦋 OO-style

use Test::Fake::HTTPD;

my $httpd = Test::Fake::HTTPD->new(
    timeout     => 5,
    daemon_args => { ... }, # HTTP::Daemon args
);

$httpd->run(sub {
    my $req = shift;
    # ...
    [ 200, [ 'Content-Type', 'text/plain' ], [ 'Hello World' ] ];
});

# Stop http server automatically at destruction time.

Notice that last line in both? The server shuts itself down when the object gets destroyed. She's self-sufficient. Main character energy fr fr. 👑

---

🌈 DESCRIPTION 🌈

Test::Fake::HTTPD is a fake HTTP server module for testing. That's it, that's the whole pitch. It's giving "I made you a server, it's fake, it's for tests, you're welcome." 💖

---

🎀 FUNCTIONS 🎀

• run_http_server { ... } — Starts HTTP server and returns the guard instance.

my $httpd = run_http_server {
    my $req = shift;
    # ...
    return $http_or_plack_or_psgi_res;
};

# can use $httpd guard object, same as OO-style
LWP::UserAgent->new->get($httpd->endpoint);

That $httpd guard object? Same one you'd get from OO-style. Reuse and slay. ✨

• run_https_server { ... } — Starts HTTPS server and returns the guard instance.

Lowkey important: if you use this method, you MUST install HTTP::Daemon::SSL. Not optional. Not "eh maybe later". MUST. 😭

extra_daemon_args
    SSL_key_file  => "certs/server-key.pem",
    SSL_cert_file => "certs/server-cert.pem";

my $httpd = run_https_server {
    my $req = shift;
    # ...
    return $http_or_plack_or_psgi_res;
};

# can use $httpd guard object, same as OO-style
my $ua = LWP::UserAgent->new(
    ssl_opts => {
        SSL_verify_mode => 0,
        verify_hostname => 0,
    },
);
$ua->get($httpd->endpoint);

---

💅 METHODS 💅

• new( %args ) — Returns a new instance. Baby server, freshly born. 🍼

my $httpd = Test::Fake::HTTPD->new(%args);

%args are, bestie:

• timeout — timeout value (default: 5)
• listen — queue size for listen (default: 5)
• host — local address to listen on (default: 127.0.0.1)
• port — TCP port to listen on (default: auto detection)

my $httpd = Test::Fake::HTTPD->new(
    timeout => 10,
    listen  => 10,
    port    => 3333,
);

• run( sub { ... } ) — Starts this HTTP server. Go go go. 🚀

$httpd->run(sub { ... });

• scheme — Returns a scheme of running, "http" or "https".

my $scheme = $httpd->scheme;

• host — Returns the address the server is listening on.
• port — Returns the TCP port the server is listening on.

my $port = $httpd->port;

• host_port — Returns the host:port from "endpoint" (e.g., "127.0.0.1:1234", "[::1]:1234").

my $host_port = $httpd->host_port;

• endpoint — Returns a URI object to the running server (e.g., "http://127.0.0.1:1234", "https://[::1]:1234"). And here's the lil quirk: if "host" returns undef, '', '0.0.0.0', or '::', then the host portion of the URI is set to "localhost". Periodt. ✨

use LWP::UserAgent;

my $res = LWP::UserAgent->new->get($httpd->endpoint);

my $url = $httpd->endpoint;
$url->path('/foo/bar');
my $res = LWP::UserAgent->new->get($url);

---

👑 AUTHOR 👑

NAKAGAWA Masaki <masaki@cpan.org> — the icon who wrote this. Respect. 🫶

---

🌸 THANKS TO 🌸

xaicron — shoutout, no cap. 💜

---

📜 LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Free as in, go off, do your thing. 💖

---

🦋 SEE ALSO 🦋

• Test::TCP
• HTTP::Daemon
• HTTP::Daemon::SSL
• HTTP::Message::PSGI

---

And that's the whole page, bestie!! This was pulled from perl v5.30.3, dated 2020-08-18, and it lives under the Test::...::HTTPD(3pm) manual — go build something fake and beautiful. 💖✨🎀🦋