Test::Override::UserAgent - Override the LWP::UserAgent to return canned responses for testing
This documentation refers to version 0.004001
package Test::My::Module::UserAgent::Configuration; # Load into configuration module use Test::Override::UserAgent for => 'configuration'; # Allow unhandled requests to be live allow_live; override_request path => '/test.html', sub { my ($request) = @_; # Do something with request and make HTTP::Response return $response; }; package main; # Load the module use Test::My::Module::UserAgent::Configuration; my $scope = Test::My::Module::UserAgent::Configuration ->configuration->install_in_scope;
This module allows for very easy overriding of the request-response cycle of LWP::UserAgent and any other module extending it. The override can be done per-scope (where the API of a module doesn't let you alter it's internal user agent object) or per-object, but modifying the user agent.
This module take a HASH of arguments to the import method that specify how this module will alter the symbol table of the package calling the import method. Without any arguments supplied, this module will not alter the symbol table. The following keys are accepted:
import
This specifies the reason this module is being imported into the calling package. The value for this is a string. By default the value is testing which specifies the module is for testing purposes and will not import anything. The other option is configuration which imports several symbols and sets up the calling package to be a configuration package. For details about making a configuration package, see Test::Override::UserAgent::Manual::ConfigurationPackage.
testing
configuration
This will construct a new configuration object to allow for configuring user agent overrides.
%attributes is a HASH where the keys are attributes (specified in the "ATTRIBUTES" section).
%attributes
$attributes is a HASHREF where the keys are attributes (specified in the "ATTRIBUTES" section).
$attributes
This is a Boolean specifying if the user agent is allowed to make any live requests (so allowing it to make requests that are not overwritten). The default is 0 which causes any requests made to a location that has not been overwritten to return an appropriate HTTP request as if the overwritten responses are the entire Internet.
0
The first argument is a HTTP::Request object. The rest of the arguments are a hash (not a hash reference) with the keys specified below. This will return either a HTTP::Request if the request had a corresponding override or undef if no override was present to handle the request. Unless the live_request_handler was specified, which changes what is returned (see below).
undef
live_request_handler
This takes a code reference that will be called if it is determined that the request should be live. The code is given one argument: the request object that was given to "handle_request". If this argument is given, then if it is determined that live requests are not permitted, "handle_request" will no longer return undef and will instead return a HTTP::Response object as normal (but won't be a successful response).
$conf->handle_request($request, live_request_handler => sub { my ($live_request) = @_; # Make the live request somehow my $response = ... # Return the response return $response; });
This will install the user agent override configuration into the current scope. The recommended install is "install_in_user_agent" but if what needs to be tested does not expose the user agent for manipulation, then that method should be used. This will return a scalar reference Test::Override::UserAgent::Scope, that until destroyed (by going out of scope, for instance) will override all LWP::UserAgent requests.
# Current config in $config { # Install in this scope my $scope = $config->install_in_scope; # Test our API ok $object->works, "The object works!"; } # $scope is destroyed, and so override configuration is removed
This will install the overrides directly in a user agent, allowing for localized overrides. This is the preferred method of overrides. This will return the user agent that has the overrides installed.
# Install into a user agent $ua_override->install_in_user_agent($ua); # Install into a new copy my $new_ua = $ua_override->install_in_user_agent($ua, clone => 1);
The first argument is the user agent object (expected to have the add_handler method) that the overrides will be installed in. After that, the method takes a hash of arguments:
add_handler
This is a Boolean specifying to clone the given user agent (with the clone method) and install the overrides into the new cloned user agent. The default is 0 to not clone the user agent.
clone
This will add a new request override to the configuration. The arguments are a plain hash (%matches) followed by a subroutine reference that will return the response.
%matches
$config->override_request(%matches, \&gen_response);
The following are they keys you may specify in %matches:
host
This is a string of the host of the requested URI. This will cause a match if the requested URI has this as the host.
$request->uri->host eq $host;
method
This is a string of the request method to match on. This will cause a match if the request uses the specified method; the method should be in uppercase.
$request->method eq $method;
path
This is a string of the path of the requested URI. This will cause a match if the requested URI has this as the path.
$request->uri->path eq $path;
port
This is the port number to match on. This will cause a match if the requested URI uses the specified port number.
$request->uri->port == $port;
scheme
This is a string of the scheme to match on. This will cause a match if the requested URI uses the specified scheme.
$request->uri->scheme eq $scheme;
uri
Added in version 0.004; be sure to require this version for this feature.
This is a string of the URI to match on. This will cause a match if the requested URI is equivilent to this.
$request->uri->canonical eq URI->new($uri)->canonical;
url
This is an alias for uri above.
This method will remove the handlers belonging to this configuration from the specified user agent. The first argument is the user agent to remove the handlers from.
The handler subroutine is what you will give to actually handle a request and return a response. The handler subroutine is always given a HTTP::Request object as the first argument, which is the request for the handler to handle.
The return value can be one of type kinds:
The return value is expected to be similar to [$code, [%headers], [@lines]]. The response is expected to be identical to the spec and will be validated. If the PSGI response is invalid according to the spec, then a response with a status code of 417 will be returned.
[$code, [%headers], [@lines]]
When a request was stopped or an error was encountered within the request-handling procedures of this module, there are some extra headers added to the response object. These include the standard diagnostic headers that LWP::UserAgent will add, with one additional header.
Client-Date
This is the current date and time the response was generated by the client.
Client-Warning
Just like with LWP::UserAgent this will be "Internal response".
"Internal response"
Client-Response-Source
This header is unique to this module, and will indicate the source module that generated the response. Typically this will always be "Test::Override::UserAgent". This provides additional information to determine that the response was generated by this module instead of by the LWP::UserAgent family of modules.
"Test::Override::UserAgent"
Carp
HTTP::Config 5.815
HTTP::Headers
HTTP::Response
LWP::UserAgent
Scalar::Util
Sub::Install 0.90
Try::Tiny
URI
namespace::clean 0.04
Douglas Christopher Wilson, <doug at somethingdoug.com>
<doug at somethingdoug.com>
Please report any bugs or feature requests to bug-test-override-useragent at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Override-UserAgent. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-test-override-useragent at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Test::Override::UserAgent
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Override-UserAgent
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Override-UserAgent
CPAN Ratings
http://cpanratings.perl.org/d/Test-Override-UserAgent
Search CPAN
http://search.cpan.org/dist/Test-Override-UserAgent/
Copyright 2010 Douglas Christopher Wilson.
This program is free software; you can redistribute it and/or modify it under the terms of either:
the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
the Artistic License version 2.0.
To install Test::Override::UserAgent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Override::UserAgent
CPAN shell
perl -MCPAN -e shell install Test::Override::UserAgent
For more information on module installation, please visit the detailed CPAN module installation guide.