NAME

    LWP::UserAgent::Mockable - Permits recording, and later playing back of
    LWP requests.

VERSION

    Version 1.10

SYNOPSIS

        # setup env vars to control behaviour, allowing them to be
        # overridden from command line.  In current case, do before
        # loading module, so will be actioned on.
    
        BEGIN {
            $ENV{ LWP_UA_MOCK } ||= 'playback';
            $ENV{ LWP_UA_MOCK_FILE } ||= 'lwp-mock.out';
        }
    
        use LWP;
        use LWP::UserAgent::Mockable;
    
        # setup a callback when recording, to allow modifying the response
    
        LWP::UserAgent::Mockable->set_record_callback( sub {
            my ( $request, $response ) = @_;
    
            print "GOT REQUEST TO: " . $request->uri;
            $response->content( lc( $response->content ) );
    
            return $response;
        } );
    
        # perform LWP request, as normal
    
        my $ua = LWP::UserAgent->new;
        my $res = $ua->get( "http://gmail.com" );
        print $res->content;
    
        # when the LWP work is done, inform LWP::UserAgent::Mockable
        # that we're finished.  Will trigger any behaviour specific to
        # the action being done, such as saving the recorded session.
    
        END {
            # END block ensures cleanup if script dies early
            LWP::UserAgent::Mockable->finished;
        }

DESCRIPTION

    This module adds session record and playback options for LWP requests,
    whilst trying to introduce as little clutter as necessary.

    When in record mode, all LWP requests and responses will be captured
    in-memory, until the finished method is called, at which point they
    will then be written out to a file. In playback mode, LWP responses are
    short-circuited, to instead return the responses that were previously
    dumped out. If neither of the above actions are requested, this module
    does nothing, so LWP requests are handled as normal.

    Most of the control of this module is done via environment variables,
    both to control the action being done (LWP_UA_MOCK env var, allowed
    values being 'record', 'playback', 'passthrough' (the default) ), and
    to control the file that is used for storing or replaying the responses
    (LWP_UA_MOCK_FILE env var, not used for 'passthrough' mode).

    The only mandatory change to incorporate this module is to call the
    'finished' method, to indicate that LWP processing is completed. Other
    than that, LWP handling can be done as-normal.

    As the initial impetus for this module was to allow mocking of external
    HTTP calls within unit tests, a couple of optional callback (one for
    each action of the valid action types), to allow for custom handling of
    responses, or to modify the response that is returned back to the
    client (this is useful for simulating the requested system being down,
    or when playing back, to modify the mocked response to reflect expected
    dynamic content).

 Methods

    As there is only a singleton instance of LWP::UserAgent::Mockable, all
    methods are class methods.

    finished() - required

      Informs LWP::UserAgent::Mockable that no further requests are
      expected, and allow it to do any post-processing that is required.

      When in 'record' mode, this will cause the playback file (controlled
      by LWP_UA_MOCK_FILE env var) to be created. When in 'playback' mode,
      this will issue a warning if there is still additional mocked
      responses that haven't been returned.

    set_record_callback( <sub {}> ) - optional

    set_playback_callback( <sub {}> ) - optional

      These optional methods allow custom callbacks to be inserted, when
      performing the relevant actions. The callback will be invoked for
      each LWP request, AFTER the request has been actioned (see
      set_record_pre_callback for a method o short-circuiting the LWP
      fetch). They will be passed in 2 parameters, an HTTP::Request and an
      HTTP::Response object. For the record callback (which is used for
      both 'record' and 'passthrough' mode) the request will be the
      HTTP::Request object used to perform the request, and the response
      the HTTP::Response result from that. In playback mode, the request
      will be the HTTP::Request object used to perform the request, and the
      response the mocked response object.

      When the callbacks are being used, they're expected to return an
      HTTP::Response object, which will be treated as the actual reply from
      the call being made. Failure to do do will result in a fatal error
      being raised.

      To clear a callback, call the relevant method, passing in no
      argument.

    set_record_pre_callback( <sub {}> ) - optional

      This callback is similar to set_record_callback, except that it will
      short-circuit the actual fetching of the remote URL. Only a single
      parameter is passed through to this callback, that being the
      HTTP::Request object. It's expected to construct an return an
      HTTP::Response object (or subclass thereof). Should anything other
      than an HTTP::Response subclass be returned, a fatal error will be
      raised.

      This callback will be invoked for both 'record' and 'passthrough'
      modes. Note that there is no analagous callback for 'playback' mode.

      To clear the callback, pass in no argument.

    set_playback_validation_callback( <sub {}> ) - optional

      This callback allows validation of the received request. It receives
      two parameters, both HTTP::Requests, the first being the actual
      request made, the second being the mocked request that was received
      when recording a session. It's up to the callback to do any
      validation that it wants, and to perform any action that is
      warranted.

      As with other callbacks, to clear, pass in no argument to the method.

    reset( <action>, <file> ) - optional

      Reset the state of mocker, allowing the action and file operation on
      to change. Will also reset all callbacks. Note that this will raise
      an error, if called whilst there are outstanding requests, and the
      finished method hasn't been called.

CAVEATS

    The playback file generated by this is not encrypted in any manner. As
    it's only using Storable to dump the file, it's easy to get at the data
    contained within, even if the requests are going to HTTPS sites. Treat
    the playback file as if it were the original data, security-wise.

SEE ALSO

      * LWP::UserAgent - The class being mocked.

      * Test::LWP::UserAgent

      * HTTP::Request

      * HTTP::Response

AUTHOR

    Mark Morgan, <makk384@gmail.com>

CONTRIBUTORS

    Michael Jemmeson, <michael.jemmeson at cpan.org>

    Kit Peters, <popefelix at cpan.org>

    Mohammad S. Anwar, <mohammad.anwar at yahoo.com>

    Slaven Rezić, <SREZIC at cpan.org>

SUPPORT

 Bugs / Feature Requests

    Please report any bugs or feature requests through the issue tracker at
    https://github.com/mjemmeson/LWP-UserAgent-Mockable/issues. You will be
    notified automatically of any progress on your issue.

 Source Code

    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    https://github.com/mjemmeson/LWP-UserAgent-Mockable

        git clone git://github.com/mjemmeson/LWP-UserAgent-Mockable.git

COPYRIGHT & LICENSE

    Copyright 2009 Mark Morgan, all rights reserved.

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