Test::...PServer(3pm)

📦 version 0.20, in ubuntu stonking

💅 Test::AnyEventFTPServer — like, the whole vibe ✨

okay bestie, gather round 🫶 this page lives in the User Contributed Perl Documentation section of the manual (so it shows up as Test::...PServer(3pm) when your terminal is being dramatic and truncating), and it's at version 0.20. It's called Test::AnyEventFTPServer and it does exactly one thing and does it gorgeously:

Test (non-blocking) ftp clients against a real FTP server 💖

🌸 SYNOPSIS 🌸

use Test2:V0;
use Test::AnyEventFTPServer;

# exit this script after 30s to avoid hung test
global_timeout_ok;

# $test_server isa AnyEvent::FTP::Server
# and          isa Test::AnyEventFTPServer
my $test_server = create_ftpserver_ok;

$test_server->command_ok('HELP')
            ->code_is(214)
            ->message_like(qr{the following commands are recognize});

# $res isa AnyEvent::FTP::Client::Response
# from that last HELP command
my $res = $test_server->res;

# $client isa AnyEvent::FTP::Client
my $client = $test_server->connect_ftpclient_ok;

# check to make sure that all FTP commands have help
$test_server->help_coverage_ok;

done_testing;

🦋 DESCRIPTION 🦋

This module makes it easy to test ftp clients against a real AnyEvent::FTP FTP server. No mocks, no pretending, we're testing against the actual thing, periodt. 💅

The FTP server is non-blocking in and does not "fork", so if you are testing a FTP client that blocks then you will need to do it in a separate process. Like, do not try to sneak a blocking client in here, it will not go well 😭.

AnyEvent::FTP::Client is a client that doesn't block and so is safe to use in testing against the server. That one is our bestie, that one gets to stay at the party. 🎀

👑 ATTRIBUTES 👑

✨ test_uri

my $uri = $test_server->test_uri

The full URL (including host, port, username and password) of the test ftp server. This is returned as URI. Everything you need to get in, all in one little string 🫶

✨ res

my $res = $test_server->res

The last AnyEvent::FTP::Client::Response object returned from the server after calling the "command_ok" method. It's giving receipts from the last thing you said. 🧾

✨ content

my $content = $test_server->content

The last content retrieved from a "list_ok", "nlst_ok" or "transfer_ok" test. Whatever the server handed over, it's sitting right here. 🍓

✨ auto_login

my $bool = $test_server->auto_login

If true (the default, iykyk) automatically login using the correct credentials. Normally if you are testing file transfers you want to keep this to the default value; if you are testing the authentication of a server context then you want to set this to false. So basically: transferring files? leave it. Testing auth? turn it off. 💯

💖 METHODS 💖

🎀 create_ftpserver_ok

my $test_server = create_ftpserver_ok;
my $test_server = create_ftpserver_ok($default_context);
my $test_server = create_ftpserver_ok($default_context, $test_name);

Create the FTP server with a random username and password for logging in. You can get the username/password from the "test_uri" attribute, or connect to the server using AnyEvent::FTP::Client automatically with the "connect_ftpclient_ok" method below. Random creds every single time, no cap 🔥

🎀 connect_ftpclient_ok

my $client = $test_server->connect_ftpclient_ok;
my $client = $test_server->connect_ftpclient_ok($test_name);

Connect to the FTP server, return the AnyEvent::FTP::Client object which can be used for testing. That's it, that's the whole method, and it's iconic for it. 💅

🎀 help_coverage_ok

$test_server->help_coverage_ok;
$test_server->help_coverage_ok($context_class);
$test_server->help_coverage_ok($context_class, $test_name);

Test that there is a "help_*" method for each "cmd_*" method in the given context class (the server's default context class is used if it isn't provided). This can also be used to test help coverage of context roles. Every command deserves help text, and this method is the friend who checks that nobody got left out 🥺

🎀 command_ok

$test_command->command_ok( $command, $arguments );
$test_command->command_ok( $command, $arguments, $test_name );

Execute the given command with the given arguments on the remote server. Fails only if a valid FTP response is not returned from the server (even error responses are okay). Like, error responses are still valid responses, we're not judging. 🙈

The response is stored in the "res" attribute.

This method returns the test server object, so you can chain this command:

$server->command_ok('HELP', 'HELP') # get help on the help command
       ->code_is(214)               # returns status code 214
       ->message_like(qr{HELP});    # the help command mentions the help command

Chaining?! slay. 💅✨

🎀 code_is

$test_server->code_is($code);
$test_server->code_is($code, $test_name);

Verifies that the status code of the last command executed matches the given code exactly. No vibes-based matching here, we're being precise. 💯

🎀 code_like

$test_server->code_like($regex);
$test_server->code_like($regex, $test_name);

Verifies that the status code of the last command executed matches the given regular expression.. (yes, two dots, we don't gatekeep punctuation 🫶)

🎀 message_like

$test_server->message_like($regex);
$test_server->message_like($regex, $test_name);

Verifies that the message portion of the response of the last command executed matches the given regular expression. The message part specifically, not the code, keep up bestie 😌

🎀 message_is

$test_server->message_is($string);
$test_server->message_is($string, $test_name);

Verifies that the message portion of the response of the last command executed matches the given string.

If the response message has multiple lines, then only one of the lines needs to match the given string. Multiline response? We only need one of them to hit, that's the rule. 🎀

🎀 list_ok

$test_server->list_ok;
$test_server->list_ok($location);
$test_server->list_ok($location, $test_name)

Execute a the "LIST" command on the given $location and wait for the results. You can see the result using the "content" attribute or test it with the "content_is" method. Waiting is part of the gig, but it's a non-blocking wait so we're fine 💖

🎀 nlst_ok

$test_server->nlst_ok;
$test_server->nlst_ok( $location );
$test_server->nlst_ok( $location, $test_name );

Execute a the "NLST" command on the given $location and wait for the results. You can see the result using the "content" attribute or test it with the "content_is" method. Same energy as list_ok, different command. 🌸

🎀 content_is

$test_server->content_is($string);
$test_server->content_is($string, $test_name);

Test that the given $string matches the content returned by the last "list_ok" or "nlst_ok" method. Direct comparison, no games. ✨

🎀 global_timeout_ok

global_timeout_ok;
global_timeout_ok($timeout);
global_timeout_ok($timeout, $test_name)

Set a global timeout on the entire test script. If the timeout is exceeded the test will exit. Handy if you have test automation and your test automation doesn't handle hung tests. Nobody wants a test that just... sits there... forever... staring at you 😭

The default timeout is 120 seconds. Two whole minutes. Generous, honestly.

🌈 AUTHOR 🌈

Author: Graham Ollis <plicease@cpan.org>

Contributors:

  • Ryo Okamoto
  • Shlomi Fish
  • José Joaquín Atria

Shoutout to the whole squad, we appreciate you 🫶💜

This software is copyright (c) 2017-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Free as in go off, queen. 👑

🦋 okay and that's the whole page!! this one shipped with perl v5.40.1 and is dated 2026-02-16, from the User Contributed Perl Documentation crew. thanks for reading my little manpage bestie, go write some non-blocking ftp tests and absolutely devour 💅✨🎀
📦 where this page comes from