Karen Etheridge > Test-LWP-UserAgent-0.022 > Test::LWP::UserAgent

Download:
Test-LWP-UserAgent-0.022.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.022   Source   Latest Release: Test-LWP-UserAgent-0.026

NAME ^

Test::LWP::UserAgent - a LWP::UserAgent suitable for simulating and testing network calls

VERSION ^

version 0.022

SYNOPSIS ^

In your application code:

    use URI;
    use HTTP::Request::Common;
    use LWP::UserAgent;

    my $useragent = $self->useragent || LWP::UserAgent->new;

    my $uri = URI->new('http://example.com');
    $uri->port('3000');
    $uri->path('success');
    my $request = POST($uri, a => 1);
    my $response = $useragent->request($request);

Then, in your tests:

    use Test::LWP::UserAgent;
    use Test::More;

    my $useragent = Test::LWP::UserAgent->new;
    $useragent->map_response(
        qr{example.com/success}, HTTP::Response->new('200', 'OK', ['Content-Type' => 'text/plain'], ''));
    $useragent->map_response(
        qr{example.com/fail}, HTTP::Response->new('500', 'ERROR', ['Content-Type' => 'text/plain'], ''));

    # now, do something that sends a request, and test how your application
    # responds to that response

DESCRIPTION ^

This module is a subclass of LWP::UserAgent which overrides a few key low-level methods that are concerned with actually sending your request over the network, allowing an interception of that request and simulating a particular response. This greatly facilitates testing of client networking code where the server follows a known protocol.

The synopsis describes a classic case where you want to test how your application reacts to various responses from the server. This module will let you send back various responses depending on the request, without having to set up a real server to test against. This can be invaluable when you need to test edge cases or error conditions that do not normally arise from the server.

There are a lot of different ways you can set up the response mappings, and hook into this module; see the documentation for the individual interface methods.

You can use a PSGI app to handle the requests - see examples/call_psgi.t in this dist, and also "register_psgi" below.

OR, you can route some or all requests through the network as normal, but still gain the hooks provided by this class to test what was sent and received:

    my $useragent = Test::LWP::UserAgent->new(network_fallback => 1);

or:

    $useragent->map_network_response(qr/real.network.host/);

    # ... generate a request...

    # and then in your tests:
    is(
        $useragent->last_useragent->timeout,
        180,
        'timeout was overridden properly',
    );
    is(
        $useragent->last_http_request_sent->uri,
        'uri my code should have constructed',
    );
    is(
        $useragent->last_http_response_received->code,
        '200',
        'I should have gotten an OK response',
    );

Ensuring the right useragent is used

Note that LWP::UserAgent itself is not monkey-patched - you must use this module (or a subclass) to send your request, or it cannot be caught and processed.

One common mechanism to swap out the useragent implementation is via a lazily-built Moose attribute; if no override is provided at construction time, default to LWP::UserAgent->new(%options).

Additionally, most methods can be called as class methods, which will store the settings globally, so that any instance of Test::LWP::UserAgent can use them, which can simplify some of your application code.

METHODS ^

All other methods from LWP::UserAgent are available unchanged.

Usage with SOAP requests ^

MOTIVATION ^

Most mock libraries on the CPAN use Test::MockObject, which is widely considered not good practice (among other things, @ISA is violated, it requires knowing far too much about the module's internals, and is very clumsy to work with). (This blog entry is one of many that chronicles its issues.)

This module is a direct descendant of LWP::UserAgent, exports nothing into your namespace, and all access is via method calls, so it is fully inheritable should you desire to add more features or override some bits of functionality.

(Aside from the constructor), it only overrides the one method in LWP::UserAgent that issues calls to the network, so real HTTP::Request and HTTP::Headers objects are used throughout. It provides a method (last_http_request_sent) to access the last HTTP::Request, for testing things like the URI and headers that your code sent to LWP::UserAgent.

SUPPORT ^

Bugs may be submitted through the RT bug tracker (or bug-Test-LWP-UserAgent@rt.cpan.org). I am also usually active on irc, as 'ether' at irc.perl.org.

ACKNOWLEDGEMENTS ^

AirG Inc., my former employer, and the first user of this distribution.

mst - Matt S. Trout <mst@shadowcat.co.uk>, for the better name of this distribution, and for the PSGI registration concept.

Also Yury Zavarin, whose Test::Mock::LWP::Dispatch inspired me to write this module, and from where I borrowed some aspects of the API.

SEE ALSO ^

AUTHOR ^

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012 by Karen Etheridge.

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

syntax highlighting: