1Test::TCP(3) User Contributed Perl Documentation Test::TCP(3)
2
6 Test::TCP - testing TCP program
7
9 use Test::TCP;
10 my $server = Test::TCP->new(
12 listen => 1,
13 code => sub {
14 my $socket = shift;
15 ...
16 },
17 );
18 my $client = MyClient->new(host => '127.0.0.1', port => $server->port);
19 undef $server; # kill child process on DESTROY
20 If using a server that can only accept a port number, e.g. memcached:
22 use Test::TCP;
24 my $memcached = Test::TCP->new(
26 code => sub {
27 my $port = shift;
28 exec $bin, '-p' => $port;
30 die "cannot execute $bin: $!";
31 },
32 );
33 my $memd = Cache::Memcached->new({servers => ['127.0.0.1:' . $memcached->port]});
34 ...
35 N.B.: This is vulnerable to race conditions, if another process binds
37 to the same port after Net::EmptyPort found it available.
38 And functional interface is available:
40 use Test::TCP;
42 test_tcp(
43 listen => 1,
44 client => sub {
45 my ($port, $server_pid) = @_;
46 # send request to the server
47 },
48 server => sub {
49 my $socket = shift;
50 # run server, calling $socket->accept
51 },
52 );
53 test_tcp(
55 client => sub {
56 my ($port, $server_pid) = @_;
57 # send request to the server
58 },
59 server => sub {
60 my $port = shift;
61 # run server, binding to $port
62 },
63 );
64
66 Test::TCP is a test utility to test TCP/IP-based server programs.
67
69 test_tcp
70 Functional interface.
71 test_tcp(
73 listen => 1,
74 client => sub {
75 my $port = shift;
76 # send request to the server
77 },
78 server => sub {
79 my $socket = shift;
80 # run server
81 },
82 # optional
83 host => '127.0.0.1', # specify '::1' to test using IPv6
84 port => 8080,
85 max_wait => 3, # seconds
86 );
87 If "listen" is false, "server" is instead passed a port number that
89 was free before it was called.
90 wait_port
92 wait_port(8080);
93 Waits for a particular port is available for connect.
95
97 my $server = Test::TCP->new(%args);
98 Create new instance of Test::TCP.
99 Arguments are following:
101 $args{auto_start}: Boolean
103 Call "$server->start()" after create instance.
104 Default: true
106 $args{code}: CodeRef
108 The callback function. Argument for callback function is:
109 $code->($socket) or $code->($port), depending on the value of
110 "listen".
111 This parameter is required.
113 $args{max_wait} : Number
115 Will wait for at most $max_wait seconds before checking port.
116 See also Net::EmptyPort.
118 Default: 10
120 $args{listen} : Boolean
122 If true, open a listening socket and pass this to the callback.
123 Otherwise find a free port and pass the number of it to the
124 callback.
125 $server->start()
127 Start the server process. Normally, you don't need to call this
128 method.
129 $server->stop()
131 Stop the server process.
132 my $pid = $server->pid();
134 Get the pid of child process.
135 my $port = $server->port();
137 Get the port number of child process.
138
140 How to invoke two servers?
141 You can call test_tcp() twice!
142 test_tcp(
144 client => sub {
145 my $port1 = shift;
146 test_tcp(
147 client => sub {
148 my $port2 = shift;
149 # some client code here
150 },
151 server => sub {
152 my $port2 = shift;
153 # some server2 code here
154 },
155 );
156 },
157 server => sub {
158 my $port1 = shift;
159 # some server1 code here
160 },
161 );
162 Or use the OO interface instead.
164 my $server1 = Test::TCP->new(code => sub {
166 my $port1 = shift;
167 ...
168 });
169 my $server2 = Test::TCP->new(code => sub {
170 my $port2 = shift;
171 ...
172 });
173 # your client code here.
175 ...
176 How do you test server program written in other languages like
178 memcached?
179 You can use exec() in child process.
180 use strict;
182 use warnings;
183 use utf8;
184 use Test::More;
185 use Test::TCP 1.08;
186 use File::Which;
187 my $bin = scalar which 'memcached';
189 plan skip_all => 'memcached binary is not found' unless defined $bin;
190 my $memcached = Test::TCP->new(
192 code => sub {
193 my $port = shift;
194 exec $bin, '-p' => $port;
196 die "cannot execute $bin: $!";
197 },
198 );
199 use Cache::Memcached;
201 my $memd = Cache::Memcached->new({servers => ['127.0.0.1:' . $memcached->port]});
202 $memd->set(foo => 'bar');
203 is $memd->get('foo'), 'bar';
204 done_testing;
206 How do I use address other than "127.0.0.1" for testing?
208 You can use the "host" parameter to specify the bind address.
209 # let the server bind to "0.0.0.0" for testing
211 test_tcp(
212 client => sub {
213 ...
214 },
215 server => sub {
216 ...
217 },
218 host => '0.0.0.0',
219 );
220 How should I write IPv6 tests?
222 You should use the "can_bind" in Net::EmptyPort function to check
223 if the program can bind to the loopback address of IPv6, as well as
224 the "host" parameter of the "test_tcp" function to specify the same
225 address as the bind address.
226 use Net::EmptyPort qw(can_bind);
228 plan skip_all => "IPv6 not available"
230 unless can_bind('::1');
231 test_tcp(
233 client => sub {
234 ...
235 },
236 server => sub {
237 ...
238 },
239 host => '::1',
240 );
241
243 Tokuhiro Matsuno <tokuhirom@gmail.com>
244
246 kazuhooku
247 dragon3
249 charsbar
251 Tatsuhiko Miyagawa
253 lestrrat
255
258 This library is free software; you can redistribute it and/or modify it
259 under the same terms as Perl itself.
260perl v5.36.0 2023-01-20 Test::TCP(3)