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.
SEE ALSO
AUTHOR
Graham Ollis <plicease@cpan.org>
COPYRIGHT AND LICENSE
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.