The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Override-UserAgent-0.001
River stage one • 1 direct dependent • 1 total dependent
++
/ Test::Override::UserAgent

NAME

Test::Override::UserAgent - Override the LWP::UserAgent to return canned responses for testing

VERSION

Version 0.001

SYNOPSIS

  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 url => '/test.html', sub {
      my ($request) = @_;

      # Do something with request and make HTTP::Response

      return $response;
  };

  package main;

  # Load the module
  use Test::Override::UserAgent for => 'testing';

DESCRIPTION

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 obejct) or per-object, but modifying the user agent.

CONSTRUCTOR

new

This will construct a new configuration object to allow for configuring user agent overrides.

new(%attributes)

%attributes is a HASH where the keys are attributes (specified in the "ATTRIBUTES" section).

new($attributes)

$attributes is a HASHREF where the keys are attributes (specified in the "ATTRIBUTES" section).

ATTRIBUTES

allow_live_requests

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.

METHODS

handle_request

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::Response 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).

live_request_handler

This takes a code reference that will be called if it is determined that the request should be live. The sode 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;
  });

install_in_scope

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

install_in_user_agent

This will install the overrides directly in a user agent, allowing for localized overrides. This is the perferred 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:

clone

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.

override_request

This will add a new request override to the configuration. The argument is a plain hash with the keys that HTTP::Config takes as specified in "Matching" in HTTP::Config. The keys may leave off the m_ prefix. The subroutine must function as specified in "HANDLER SUBROUTINE".

uninstall_from_user_agent

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.

HANDLER SUBROUTINE

The handler subroutine is what you will give to actualy 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:

HTTP::Response object
PSGI-like response array reference

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.

DEPENDENCIES

AUTHOR

Douglas Christopher Wilson, <doug at somethingdoug.com>

BUGS AND LIMITATIONS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

  perldoc Test::Override::UserAgent

You can also look for information at:

LICENSE AND COPYRIGHT

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.