1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
[](https://travis-ci.org/Corion/Test-HTTP-LocalServer)
[](https://ci.appveyor.com/project/Corion/Test-HTTP-LocalServer)
# NAME
Test::HTTP::LocalServer - spawn a local HTTP server for testing
# SYNOPSIS
use HTTP::Tiny;
my $server = Test::HTTP::LocalServer->spawn(
request_pause => 1, # wait one second before accepting the next request
);
my $res = HTTP::Tiny->new->get( $server->url );
print $res->{content};
$server->stop;
# DESCRIPTION
This module implements a tiny web server suitable for running "live" tests
of HTTP clients against it. It also takes care of cleaning `%ENV` from settings
that influence the use of a local proxy etc.
Use this web server if you write an HTTP client and want to exercise its
behaviour in your test suite without talking to the outside world.
# METHODS
## `Test::HTTP::LocalServer->spawn %ARGS`
my $server = Test::HTTP::LocalServer->spawn;
This spawns a new HTTP server. The server will stay running until
$server->stop
is called. Ideally, you explicitly call `->stop` or use
undef $server
before the main program ends so that the program exit code reflects the
real exit code and not the chlid exit code.
Valid arguments are :
- `html =>` scalar containing the page to be served
If this is not specified, an informative default page will be used.
- `request_pause =>` number of seconds to sleep before accepting the next
request
If your system is slow or needs to wait some time before a socket connection
is ready again, use this parameter to make the server wait a bit before
handling the next connection.
- `file =>` filename containing the page to be served
- `debug => 1` to make the spawned server output debug information
- `eval =>` string that will get evaluated per request in the server
Try to avoid characters that are special to the shell, especially quotes.
A good idea for a slow server would be
eval => sleep+10
All served HTML will have the first %s replaced by the current location.
The following entries will be removed from `%ENV` when making a request:
HTTP_PROXY
http_proxy
HTTP_PROXY_ALL
http_proxy_all
HTTPS_PROXY
https_proxy
CGI_HTTP_PROXY
ALL_PROXY
all_proxy
## `$server->port`
This returns the port of the current server. As new instances
will most likely run under a different port, this is convenient
if you need to compare results from two runs.
## `$server->url`
This returns the [URI](https://metacpan.org/pod/URI) where you can contact the server. This url
is valid until the `$server` goes out of scope or you call
$server->stop;
The returned object is a copy that you can modify at your leisure.
## `$server->server_url`
This returns the [URI](https://metacpan.org/pod/URI) object of the server URL. Use ["$server->url"](#server-url) instead.
Use this object if you want to modify the hostname or other properties of the
server object.
Consider this basically an emergency accessor. In about every case,
using `->url()` does what you want.
## `$server->stop`
This stops the server process by requesting a special
url.
## `$server->kill`
This kills the server process via `kill`. The log
cannot be retrieved then.
## `$server->get_log`
This returns the
output of the server process. This output will be a list of
all requests made to the server concatenated together
as a string.
## `$server->local`
my $url = $server->local('foo.html');
# file:///.../foo.html
Returns an URL for a local file which will be read and served
by the webserver. The filename must
be a relative filename relative to the location of the current
program.
# URLs implemented by the server
## arbitrary content `$server->content($html)`
$server->content(<<'HTML');
<script>alert("Hello World");</script>
HTML
The URL will contain the HTML as supplied. This is convenient for supplying
Javascript or special URL to your user agent.
## download `$server->download($name)`
This URL will send a file with a `Content-Disposition` header and indicate
the suggested filename as passed in.
## 302 redirect `$server->redirect($target)`
This URL will issue a redirect to `$target`. No special care is taken
towards URL-decoding `$target` as not to complicate the server code.
You need to be wary about issuing requests with escaped URL parameters.
## 401 basic authentication challenge `$server->basic_auth($user, $pass)`
This URL will issue a 401 basic authentication challenge. The expected user
and password are encoded in the URL.
my $challenge_url = $server->basic_auth('foo','secret');
my $wrong_pw = URI->new( $challenge_url );
$wrong_pw->userinfo('foo:hunter2');
$res = HTTP::Tiny->new->get($wrong_pw);
is $res->{status}, 401, "We get the challenge with a wrong user/password";
## 404 error `$server->error_notfound($target)`
This URL will response with status code 404.
## Timeout `$server->error_timeout($seconds)`
This URL will send a 599 error after `$seconds` seconds.
## Timeout+close `$server->error_close($seconds)`
This URL will send nothing and close the connection after `$seconds` seconds.
## Error in response content `$server->error_after_headers`
This URL will send headers for a successful response but will close the
socket with an error after 2 blocks of 16 spaces have been sent.
## Chunked response `$server->chunked`
This URL will return 5 blocks of 16 spaces at a rate of one block per second
in a chunked response.
## Surprisingly large bzip2 encoded response `$server->bzip2`
This URL will return a short HTTP response that expands to 16M body.
## Surprisingly large gzip encoded response `$server->gzip`
This URL will return a short HTTP response that expands to 16M body.
## Other URLs
All other URLs will echo back the cookies and query parameters.
# EXPORT
None by default.
# COPYRIGHT AND LICENSE
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
Copyright (C) 2003-2024 Max Maischein
# AUTHOR
Max Maischein, <corion@cpan.org>
Please contact me if you find bugs or otherwise improve the module. More tests
are also very welcome !
# SEE ALSO
[WWW::Mechanize](https://metacpan.org/pod/WWW%3A%3AMechanize),[WWW::Mechanize::Shell](https://metacpan.org/pod/WWW%3A%3AMechanize%3A%3AShell),[WWW::Mechanize::Firefox](https://metacpan.org/pod/WWW%3A%3AMechanize%3A%3AFirefox)
|
