Ensuring the right useragent is used

One common mechanism to swap out the useragent implementation is via a lazily-built Moose attribute; if no override is provided at construction time, default to "LWP::UserAgent->new(%options)".

Additionally, most methods can be called as class methods, which will store the settings globally, so that any instance of Test::LWP::UserAgent can use them, which can simplify some of your application code.

"new"

Plus, this option is added:

•

"network_fallback => <boolean>"

If true, requests passing through this object that do not match a previously-configured mapping or registration will be directed to the network. (To only divert matched requests rather than unmatched requests, use "map_network_response", see below.)

This option is also available as a read/write accessor via "$useragent->network_fallback(<value?>)".

All other methods below may be called on a specific object instance, or as a class method. If called as on a blessed object, the action performed or data returned is limited to just that object; if called as a class method, the action or data is global.

"map_response($request_specification, $http_response)"

The request match specification can be described in multiple ways:

• string

  The string is matched identically against the "host" field of the URI in the request.

      $test_ua->map_response('example.com', HTTP::Response->new('500'));
      

• regexp

  The regexp is matched against the URI in the request.

      $test_ua->map_response(qr{foo/bar}, HTTP::Response->new('200'));
      $test_ua->map_response(qr{baz/quux}, HTTP::Response->new('500'));
      

• code

  The provided coderef is passed a single argument, the HTTP::Request, and returns a boolean indicating if there is a match.

      # matches all GET and POST requests
      $test_ua->map_response(sub {
              my $request = shift;
              return 1 if $request->method eq 'GET' || $request->method eq 'POST';
          },
          HTTP::Response->new('200'),
      );
      

• HTTP::Request object

  The HTTP::Request object is matched identically (including all query parameters, headers etc) against the provided object.

The response can be represented in multiple ways:

• a literal HTTP::Response object:

      HTTP::Response->new(...);
      

• as a coderef that is run at the time of matching, with the request passed as the single argument:

      sub {
          my $request = shift;
          return HTTP::Response->new(...);
      }
      

• a blessed object that implements the "request" method, which will be saved as a coderef thusly (this allows you to use your own dispatcher implementation):

      sub {
          my $request = shift;
          return $response->request($request);
      }
      

Instance mappings take priority over global (class method) mappings - if no matches are found from mappings added to the instance, the global mappings are then examined. When no matches have been found, a 404 response is returned.

This method returns the "Test::LWP::UserAgent" object or class.

"map_network_response($request_specification)"

If called on an instance, all options passed to the constructor (e.g. timeout) are used for making the real network call. If called as a class method, a pristine LWP::UserAgent object with no customized options will be used instead.

This method returns the "Test::LWP::UserAgent" object or class.

"unmap_all(instance_only?)"

When called as an object method, removes all mappings both globally and on this instance, unless a true value is passed as an argument, in which only mappings local to the object will be removed. (Any true value will do, so you can pass a meaningful string.)

This method returns the "Test::LWP::UserAgent" object or class.

"register_psgi($domain, $app)"

You can also use "register_psgi" with a regular expression as the first argument, or any of the other forms used by "map_response", if you wish, as calling "$test_ua->register_psgi($domain, $app)" is equivalent to:

    $test_ua->map_response(
        $domain,
        sub { HTTP::Response->from_psgi($app->($_[0]->to_psgi)) },
    );

This feature is useful for testing your PSGI applications, or for simulating a server so as to test your client code.

You might find using Plack::Test or Plack::Test::ExternalServer easier for your needs, so check those out as well.

This method returns the "Test::LWP::UserAgent" object or class.

"unregister_psgi($domain, instance_only?)"

When called as an object method, removes a domain registration that was made both globally and locally, unless a true value was passed as the second argument, in which case only the registration local to the object will be removed. This allows a different mapping made globally to take over.

If you want to mask a global registration on just one particular instance, then add "undef" as a mapping on your instance:

    $useragent->map_response($domain, undef);

This method returns the "Test::LWP::UserAgent" object or class.

"last_http_request_sent"

Note that this is also available via "last_http_response_received->request".

"last_http_response_received"

"last_useragent"

"network_fallback"

"send_request($request)"

All other methods from LWP::UserAgent are available unchanged.

SOAP::Lite

    use SOAP::Lite;
    use SOAP::Transport::HTTP;
    $SOAP::Transport::HTTP::Client::USERAGENT_CLASS = 'Test::LWP::UserAgent';

You must then make all your configuration changes and mappings globally.

See also "CHANGING THE DEFAULT USERAGENT CLASS" in SOAP::Transport.

XML::Compile::SOAP

    my $call = $wsdl->compileClient(
        $interface_name,
        transport => XML::Compile::Transport::SOAPHTTP->new(
            user_agent => $useragent,
            address => $wsdl->endPoint,
        ),
    );

See also "Adding HTTP headers" in XML::Compile::SOAP::FAQ.