1Test::TCP(3)          User Contributed Perl Documentation         Test::TCP(3)
2
3
4

NAME

6       Test::TCP - testing TCP program
7

SYNOPSIS

9           use Test::TCP;
10
11           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
21       If using a server that can only accept a port number, e.g. memcached:
22
23           use Test::TCP;
24
25           my $memcached = Test::TCP->new(
26               code => sub {
27                   my $port = shift;
28
29                   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
36       N.B.: This is vulnerable to race conditions, if another process binds
37       to the same port after Net::EmptyPort found it available.
38
39       And functional interface is available:
40
41           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
54           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

DESCRIPTION

66       Test::TCP is a test utility to test TCP/IP-based server programs.
67

METHODS

69       test_tcp
70           Functional interface.
71
72               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
88           If "listen" is false, "server" is instead passed a port number that
89           was free before it was called.
90
91       wait_port
92               wait_port(8080);
93
94           Waits for a particular port is available for connect.
95

Object Oriented interface

97       my $server = Test::TCP->new(%args);
98           Create new instance of Test::TCP.
99
100           Arguments are following:
101
102           $args{auto_start}: Boolean
103               Call "$server->start()" after create instance.
104
105               Default: true
106
107           $args{code}: CodeRef
108               The callback function. Argument for callback function is:
109               "$code->($socket)" or "$code->($port)", depending on the value
110               of "listen".
111
112               This parameter is required.
113
114           $args{max_wait} : Number
115               Will wait for at most $max_wait seconds before checking port.
116
117               See also Net::EmptyPort.
118
119               Default: 10
120
121           $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
126       $server->start()
127           Start the server process. Normally, you don't need to call this
128           method.
129
130       $server->stop()
131           Stop the server process.
132
133       my $pid = $server->pid();
134           Get the pid of child process.
135
136       my $port = $server->port();
137           Get the port number of child process.
138

FAQ

140       How to invoke two servers?
141           You can call test_tcp() twice!
142
143               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
163           Or use the OO interface instead.
164
165               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
174               # your client code here.
175               ...
176
177       How do you test server program written in other languages like
178       memcached?
179           You can use "exec()" in child process.
180
181               use strict;
182               use warnings;
183               use utf8;
184               use Test::More;
185               use Test::TCP 1.08;
186               use File::Which;
187
188               my $bin = scalar which 'memcached';
189               plan skip_all => 'memcached binary is not found' unless defined $bin;
190
191               my $memcached = Test::TCP->new(
192                   code => sub {
193                       my $port = shift;
194
195                       exec $bin, '-p' => $port;
196                       die "cannot execute $bin: $!";
197                   },
198               );
199
200               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
205               done_testing;
206
207       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
210               # 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
221       How should I write IPv6 tests?
222           You should use the `Net::EmptyPort::can_bind` function to check if
223           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
227               use Net::EmptyPort qw(can_bind);
228
229               plan skip_all => "IPv6 not available"
230                   unless can_bind('::1');
231
232               test_tcp(
233                   client => sub {
234                       ...
235                   },
236                   server => sub {
237                       ...
238                   },
239                   host => '::1',
240               );
241

AUTHOR

243       Tokuhiro Matsuno <tokuhirom@gmail.com>
244

THANKS TO

246       kazuhooku
247
248       dragon3
249
250       charsbar
251
252       Tatsuhiko Miyagawa
253
254       lestrrat
255

SEE ALSO

LICENSE

258       This library is free software; you can redistribute it and/or modify it
259       under the same terms as Perl itself.
260
261
262
263perl v5.28.0                      2018-07-15                      Test::TCP(3)
Impressum