Test::UNIXSock(3pm)

✨ NAME ✨

Test::UNIXSock — okay so bestie, it's a whole module for testing your UNIX domain socket program 💅 it lives in the perl manual pages (that's the 3pm part, iykyk) and honestly? iconic.

---

🦋 SYNOPSIS 🦋

The vibe is: you spin up a server, you point a client at it, you yeet the server when you're done. Watch:

use Test::UNIXSock;

my $server = Test::UNIXSock->new(
    code => sub {
        my $path = shift;
        ...
    },
);
my $client = MyClient->new( sock => $server->path );
undef $server; # kill child process on DESTROY

bestie the undef $server; is not optional energy — that's the "kill child process on DESTROY" moment, the child process gets cleaned up right there 😭 don't leave it hanging fr fr.

Now here's the memcached serve, because yes we do that too 🌸

use Test::UNIXSock;

my $memcached = Test::UNIXSock->new(
    code => sub {
        my $path = shift;

        exec $bin, '-s' => $path;
        die "cannot execute $bin: $!";
    },
);
my $memd = Cache::Memcached->new({servers => [$memcached->path]});
...

And guess what, there's a functional interface too, for when you don't feel like doing the object thing 👑

use Test::UNIXSock;
test_unix_sock(
    client => sub {
        my ($path, $server_pid) = @_;
        # send request to the server
    },
    server => sub {
        my $path = shift;
        # run server
    },
);

---

🎀 DESCRIPTION 🎀

Test::UNIXSock is a test utility for testing your UNIX domain socket server programs. no cap, that's literally the whole job and it does it flawlessly.

Also, important lore: this module is based on Test::TCP. it's the socket-flavored sibling, periodt 💜

---

🌈 METHODS 🌈

⭐ test_unixsock ⭐

Functional interface, bestie. Like this:

test_unixsock(
    client => sub {
        my $path = shift;
        # send request to the server
    },
    server => sub {
        my $path = shift;
        # run server
    },
    # optional
    path => "/tmp/mytest.sock", # if not specified, create a sock in tmpdir
    max_wait => 3, # seconds
);

note the cuteness: path is optional — if you don't specify it, it just creates a sock in the tmpdir for you 🧚 and max_wait is in seconds.

🍓 wait_unix_sock 🍓

wait_unix_sock({ path => $path });

It waits for a particular path is available for connect. that's it, that's the function — it just hangs out patiently until the path is ready to connect. main character patience energy ✨

👑 Object Oriented interface 👑

my $server = Test::UNIXSock->new(%args);

Creates a brand new instance of Test::UNIXSock. slay.

The arguments are giving very much:

• $args{auto_start}: Boolean — it calls $server->start() after it creates the instance for you 💖 Default: true
• $args{code}: CodeRef — the callback function, the whole point honestly. The argument it gets handed is: $code->($pid). This parameter is required — no code, no server, no vibes 😭
• $args{max_wait} : Number — it will wait for at most $max_wait seconds before checking port. Also peep Net::EmptyPort. Default: 10

$server->start()

Starts the server process. Normally, you don't need to call this method — it's already handled for you, bestie, don't stress 🙈

$server->stop()

Stops the server process. bye bye 👋

my $pid = $server->pid();

Gets the pid of the child process. cute little number.

my $port = $server->port();

Gets the port number of the child process. also cute.

---

💀 FAQ 💀

See also the Test::TCP FAQ section — it's where all the answers at, fr fr. (iykyk) 🫶

---

🦄 AUTHOR 🦄

Fujiwara Shunichiro <fujiwara.shunichiro@gmail.com> — absolute legend, thank you for your service 🌸

---

💜 SEE ALSO 💜

• Test::TCP — the parent, the blueprint, the blueprint's blueprint 🎀

---

🫧 LICENSE 🫧

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. it's free real estate, bestie 💖

And the origin story: this module is based on Test::TCP. copyright (c) 2013 by Tokuhiro Matsuno <tokuhirom@gmail.com>.

---

okay that's the whole page! this came out of perl v5.36.0 on 2022-10-16 under the title Test::UNIXSock(3pm) — and with that, we are so done here 💅✨ go write some socket tests, you got this 👑