NAME

Test2::Tools::HTTP::UA - User agent wrapper for Test2::Tools::HTTP

VERSION

version 0.12

SYNOPSIS

Use a wrapper:

 my $wrapper = Test2::Tools::HTTP::MyUAWrapper->new($ua);
 
 # returns a HTTP::Response object
 # or throws an error on a connection error
 my $res = $wrapper->request($req);

Write your own wrapper:

 package Test2::Tools::HTTP::UA::MyUAWrapper;
 
 use parent 'Test2::Tools::HTTP::UA';
 
 sub instrument
 {
   my($self) = @_;
   my $ua = $self->ua;  # the user agent object
   my $apps = $self->apps;
 
   # instrument $ua so that when requests
   # made against URLs in $apps the responses
   # come from the apps in $apps.
   ...
 }
 
 sub request
 {
   my $self = shift;
   my $req  = shift;   # this isa HTTP::Request
   my %options = @_;
 
   my $self = $self->ua;
   my $res;
 
   if($options{follow_redirects})
   {
     # make a request using $ua, store
     # result in $res isa HTTP::Response
     # follow any redirects if $ua supports
     # that.
     my $res = eval { ... };
 
     # on a CONNECTION error, you should throw
     # an exception using $self->error.  This should
     # NOT be used for 400 or 500 responses that
     # actually come from the remote server or
     # PSGI app.
     if(my $error = $@)
     {
       $self->error(
        "connection error: " . ($res->decoded_content || $warning),
       );
     }
   }
   else
   {
     # same as the previous block, but should
     # NOT follow any redirects.
     ...
   }
 
   $res;
 }
 
 __PACKAGE__->register('MyUA', 'instance');

DESCRIPTION

This is the base class for user agent wrappers used by Test2::Tools::HTTP. The idea is to allow the latter to work with multiple user agent classes without having to change the way your .t file interacts with Test2::Tools::HTTP. By default Test2::Tools::HTTP uses LWP::UserAgent and in turn uses Test2::Tools::HTTP::UA::LWP as its user agent wrapper.

CONSTRUCTOR

new

 my $wrapper = Test2::Tools::HTTP::UA->new($ua);

Creates a new wrapper.

METHODS

ua

 my $ua = $wrapper->ua;

Returns the actual user agent object. This could be any user agent object, such as a LWP::UserAgent, HTTP::Simple, or Mojo::UserAgent, but generally your wrapper only needs to support ONE user agent class.

apps

 my $apps = $wrapper->apps;
 my $apps = Test2::Tools::HTTP::UA->apps;

This returns an instance of Test2::Tools::HTTP::Apps used by your wrapper. It can be used to lookup PSGI apps by url.

Because the apps object is a singleton, you may also call this as a class method.

error

 $wrapper->error($message);
 $wrapper->error($message, $response);

This throws an exception that Test2::Tools::HTTP understands to be a connection error. This is the preferred way to handle a connection error from within your request method.

The second argument is an optional instance of HTTP::Response. In the event of a connection error, you won't have a response object from the actual remote server or PSGI application. Some user agents (such as LWP::UserAgent) produce a synthetic response object. You can stick it here for diagnostic purposes. You should NOT create your own synthetic response object though, only use this argument if your user agent produces a faux response object.

register

 Test2::Tools::HTTP::UA->register($class, $type);

Register your wrapper class with Test2::Tools::HTTP::UA. $class is the user agent class. $type is either class for classes or instance for instances, meaning your wrapper works with a class or an instance object.

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

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