/ 
Test-Mock-LWP-Dispatch-0.08
River stage two • 11 direct dependents • 14 total dependents
/ Test::Mock::LWP::Dispatch

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 Mišković

SEE ALSO

http://github.com/tadam/Test-Mock-LWP-Dispatch

Test::Mock::LWP

LWP::UserAgent

AUTHOR

Yury Zavarin <yury.zavarin@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Yury Zavarin.

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