NAME

Test::Mock::LWP::Dispatch - mocks LWP::UserAgent and dispatches your requests/responses

VERSION

version 0.08

SYNOPSIS

  # in your *.t
  use Test::Mock::LWP::Dispatch;
  use HTTP::Response;

  # global mappings for requests and responses for LWP::UserAgent
  $mock_ua->map('http://example.com', HTTP::Response->new(...));
  # or
  $mock_ua->map(qr!^http://example.com/page!, sub { my $request = shift;
                                                    # ... create $response
                                                    return $response; });

  # or make local mappings
  my $ua = LWP::UserAgent->new;
  $ua->map(...);

DESCRIPTION

This module is intended for testing a code that heavily uses LWP::UserAgent.

Assume that a function you want to test makes three different requests to a server and expects to get some content from the server. To test this function you should setup request/response mappings for mocked UserAgent and test it.

For doing something with mappings, here are methods "map", "unmap" and "unmap_all". For controlling context of these mappings (whether it applies to all LWP::UserAgent-s created in your code or only to a specific one) you need to call these functions for exported $mock_ua object (global mapping) or for newly created LWP::UserAgent (local mappings).

See also Test::Mock::LWP, it provides mocked LWP objects for you, so probably you can solve your problems with that module too.

METHODS

simple_request($req)

This is the only method of LWP::UserAgent that get mocked. When you call $ua->get(...) or $ua->head(...) or just get() from LWP::Simple, at some point it will call "simple_request()" method. So there is no need to mock anything else as long as the desired goal is the ability to control responses to your requests.

In this module "simple_request()" loops through your local and global mappings (in this order) and returns response on a first matched mapping. If no matches found, then "simple_request()" returns HTTP::Response with 404 code.

Be accurate: method loops through mappings in order of adding these mappings.

map($req_descr, $resp_descr)

Maps $req_descr to the corresponding $resp_descr.

$req_descr determines how to match an incoming request with a mapping.

$resp_descr determines what will be returned if the incoming request matches with $req_descr.

Calling this method for exported $mock_ua will make global mappings applied to all newly created LWP::UserAgent-s. Calling this method for a separately created LWP::UserAgent will apply the mapping only to that object.

Request description $req_descr can be:

string: Represents uri for exact match with the incoming request uri.
regexp: Incoming request uri will be checked against this regexp.
code: An arbitrary coderef that takes incoming HTTP::Request and returns true if this request matched.
HTTP::Request object: Incoming request will match with this object if they are exactly the same: all the query parameters, headers and so on must be identical.

Response description $resp_descr can be:

HTTP::Response object: This object will be returned.
code: An arbitrary coderef that takes incoming request as parameter and returns HTTP::Response object.

Method returns index of your mapping. You can use it in "unmap".

map_passthrough($req_descr): Will pass through the $req_descr to actual LWP::UserAgent. See map for $req_descr.
Example to let LWP::UserAgent handle all file:// urls: "$mock_ua->map_passthrough(qr{^file://});"
unmap($map_index): Deletes a mapping by index.
unmap_all: Deletes all mappings.

SWITCHES

DEFAULT_REQUEST_HEADERS

LWP::UserAgent sets default headers for requests by calling LWP::UserAgent->prepare_request().

Previous versions (<= 0.05) of Test:Mock::LWP::Dispatch didn't intercept this call in overridden "simple_request()".

Now Test::Mock::LWP::Dispatch does it by default.

If for some reason you want to get back the previous behaviour of the module, set the following variable off:

$Test::Mock::LWP::Dispatch::DEFAULT_REQUEST_HEADERS = 0;

MISCELLANEOUS

This mock object doesn't call "fake_new()". So when you prepare response using coderef, you can be sure that "User-Agent" header will be untouched and so on.

ACKNOWLEDGEMENTS

Mike Doherty

Andreas König

Ash Berlin

Joe Papperello

Slobodan Mišković

AUTHOR

Yury Zavarin <yury.zavarin@gmail.com>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.