/ 
Test2-Tools-HTTP-0.12
River stage one • 7 direct dependents • 7 total dependents
⭐ Starred 0 GitHub stars
/ Test2::Tools::HTTP::UA

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

Test2::Tools::HTTP

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.