NAME

Test::LWP::MockSocket::http - Inject arbitrary data as socket data for LWP::UserAgent

SYNOPSIS

    use Test::LWP::MockSocket::http;
    use LWP::UserAgent;
    #   $LWP_Response is exported by this module
    $LWP_Response = "HTTP/1.0 200 OK\r\n\r\nSome Response Text";
    my $ua = LWP::UserAgent->new();
    $ua->proxy("http", "http://1.2.3.4:56");
    my $http_response = $ua->get("http://www.foo.com/bar.html");
    
    $http_response->code;       #200
    $http_response->content;    # "Some response text"
    $LWP_SocketArgs->{PeerAddr} # '1.2.3.4'

DESCRIPTION

This module, when loaded, mangles some functions in LWP::Protocol::http which will emulate a real socket. LWP is used as normally as much as possible.

Effort has been made to maintain the exact behavior of Net::HTTP and LWP::Protocol::http.

Two variables are exported, $LWP_Response which should contain raw HTTP 'data', and $LWP_SocketArgs which contains a hashref passed to the socket's new constructor. This is helpful for debugging complex LWP::UserAgent subclasses (or wrappers) which modify possible connection settings.

EXPORTED SYMBOLS

Following the inspiration of Test::Mock::LWP, two package variables will nicely invade your namespace; they are $LWP_Response which contains a 'response thingy' (see below) and $LWP_SocketArgs which contains a hashref of options that LWP thought it would pass to IO::Socket::INET or IO::Socket::SSL.

In addition, you can use mocksock_response as an accessor to the $LWP_Response, if you absolutely must.

RESPONSE VARIABLE

It was mentioned that $LWP_Response is a 'thingy', and this is because it can be three things:

Scalar

This is the simplest way to use this module, and it will simply copy the contents of the scalar verbatim into LWP's read buffers.

Array Reference

This functions like the Scalar model, except that it will cycle through each of the elements in the array for each request, exhausting them - I don't know what happens if you overrun the array - and your test code really shouldn't be doing anything that causes it anyway.

Code Reference

This is the most entertaining of the three. The handler is called with three arguments. The first is the raw request data as received from LWP's serialization methods. The second is an HTTP::Request object which is pretty much just there for your convenience (this is a test module, the more information, the better, and performance is not a big issue), and the last is the socket options found in $LWP_SocketArgs, again, for convenience.

CAVEATS/BUGS

Probably many. This relies on mainly undocumented behavior and features of LWP and is likely to break. In particular, the module test tries to ensure that the mock socket works together with LWP::ConnCache.

Depending on how LWP handles POST requests and other, perhaps more exotic requests, this module might break. Then again, if you find a need to use this module in the first place, you probably Know What You Are Doing(TM).

RATIONALE

I wrote this for testing code which used LWP and its subclasses heavily, but still desired the full functionality of LWP::UserAgent (if you look closely enough, you will see that the same HTTP::Request object which is passed to LWP is not the actual one sent on the wire, and the HTTP::Response object returned by LWP methods is not the same one received on the wire).

ACKNOWLEDGEMENTS

Thanks to mst for helping me with the difficult task of selecting the module name

AUTHOR AND COPYRIGHT

Copyright 2011 M. Nunberg

You may use and distribute this software under the terms of the GNU General Public License Version 2 or higher.