🌻 📖 Test2::Tools::HTTP::UA


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


version 0.11


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;
     # 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 = $@)
        "connection error: " . ($res->decoded_content || $warning),
     # same as the previous block, but should
     # NOT follow any redirects.
 __PACKAGE__->register('MyUA', 'instance');


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.



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

Creates a new wrapper.



 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.


 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.


 $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.


 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.




Graham Ollis <plicease@cpan.org>


This software is copyright (c) 2018-2022 by Graham Ollis.

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