Perlbal::Test(3pm)

💖 Perlbal::Test 💖

okay bestie, so this is the Perlbal::Test page from the User Contributed Perl Documentation — it's a whole test harness for a perlbal server, and honestly? she's giving "quietly holding the entire test suite together" energy. 🫶

---

✨ NAME ✨

Perlbal::Test — the test harness for the perlbal server, no cap. 🎀

---

🌸 SYNOPSIS 🌸

#  my $msock = Perlbal::Test::start_server();

that's it, that's the whole vibe. one line and you're in. 💅

---

🦋 DESCRIPTION 🦋

Perlbal::Test gives you access to a perlbal server running on the local host, purely for testing purposes. it's not here to serve your production traffic, she's here to be poked at. 🧚

the server can be one of three things, and honestly the range:

• an already-existing server
• a child process
• the current process

and then there's a whole lil' friend group of functions provided to interact with the server. let's meet them. 🌈

---

👑 FUNCTIONS 👑

🌟 mgmt_port()

return the current management port number. that's it. that's the function. short queen. ✨

💅 dump_res($http_response)

return a readable string, formatted from an HTTP::Response object.

heads up tho — only the first 80 characters of returned content are returned. so like, don't expect the whole novel, you're getting the preview. 😭

🎀 tempdir()

return a newly created temporary directory.

and the best part? the directory gets removed automatically upon program exit. self-cleaning, we love a low-maintenance icon. 🧹✨

🦋 new_port()

return the next free port number in the series.

port numbers are assigned starting at 60000. remember that number, she comes back later. 👀

⭐ test_port()

return 1 if the port is free to use for listening on $free_port, else return 0.

vibe check for ports, fr fr. 🩺

🍓 filecontent($file>

return a string containing the contents of the file $file.

if $file cannot be opened, then return undef. no file, no content, no drama. 🙈

🌸 foreach_aio($callback)

set the server into each AIO mode — that's none and ioaio — and call the specified callback function with the mode name as argument.

so your callback gets told which mode it's in. considerate. 💜

🔥 manage($cmd, %opts)

send a command $cmd to the server, and return the response line from the server.

the optional arguments are:

• quiet_failure => 1 — output a warning if the response indicated an error, unless $opts{quiet_failure} is true, or the command was 'shutdown' (which doesn't return a response). yeah, shutdown just ghosts you, it's not gonna reply. 💀

🌈 manage_multi($cmd)

send a command $cmd to the server, and return a multi-line response.

return the number zero if there was an error or no response. zero means bad vibes here, don't @ me. 😤

🧚 start_server($conf)

optionally start a perlbal server and return a socket connected to its management port.

the argument $conf is a string specifying initial configuration commands.

now here's where it branches, bestie, pay attention:

• if the environment variable TEST_PERLBAL_FOREGROUND is set to a true value, then a server will be started in the foreground, in which case this function does not return. when the server function finishes, exit() will be called to terminate the process. so like, you're committing to the bit. 😭
• if the environment variable TEST_PERLBAL_USE_EXISTING is set to a true value, then a socket will be returned which is connected to an existing server's management port. reusing, recycling, sustainable queen. ♻️
• otherwise, a child process is forked and a socket is returned which is connected to the child's management port. the classic route. 🐣

the management port is assigned automatically, and it's a new port number each time this function is called. the starting port number is 60000. told you she'd come back. 👑

🫶 msock()

return a reference to the socket connected to the server's management port. the main character socket, literally. ✨

💜 ua()

return a new instance of LWP::UserAgent. fresh user agent, fresh start, new me energy. 🦋

🎀 wait_on_child($pid, $port)

return a socket which is connected to a child process.

• $pid specifies the child process id
• $port is the port number on which the child is listening

several attempts are made — so she's patient, she tries again — but if the child dies or a connection cannot be made within 5 seconds, then this function dies with an error message. five seconds, then it's over. ⏰💀

⭐ resp_from_sock($sock)

read an HTTP response from a socket and return it as an HTTP::Response object.

two modes, pick your fighter:

• in scalar mode, return only the $http_response object.
• in array mode, return an array of ($http_response, $firstline) where $firstline is the first line read from the socket, for example:

HTTP/1.1 200 OK

look at her. iconic. 🎉

---

friendly reminder bestie: this whole thing is for testing purposes — please don't build your empire on it, that's not what she's for. 🫶

---

and that's the page!! perl v5.34.0, dated 2022-06-28 — yeah she's been around a minute and she's still slaying. thanks for coming to my ted talk, mwah, bye bestie 💖💅✨