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


version 0.08


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

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

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


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.



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:


Represents uri for exact match with the incoming request uri.


Incoming request uri will be checked against this regexp.


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.


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.


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://});


Deletes a mapping by index.


Deletes all mappings.



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;


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.


Mike Doherty

Andreas König

Ash Berlin

Joe Papperello

Slobodan Mišković





Yury Zavarin <>


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.