Mojo::UserAgent::Mockable - A Mojo User-Agent that can record and play back requests without Internet connectivity, similar to LWP::UserAgent::Mockable
version 1.58
my $ua = Mojo::UserAgent::Mockable->new( mode => 'record', file => '/path/to/file' );
my $tx = $ua->get($url);
# Then later...
my $ua = Mojo::UserAgent::Mockable->new( mode => 'playback', file => '/path/to/file' );
my $tx = $ua->get($url);
# This is the same content as above. The saved response is returned, and no HTTP request is
# sent to the remote host.
my $reconstituted_content = $tx->res->body;
Mode to operate in. One of:
-
passthrough
Operates like Mojo::UserAgent in all respects. No recording or playback happen.
-
record
Records all transactions made with this instance to the file specified by "file".
-
playback
Plays back transactions recorded in the file specified by "file"
-
lwp-ua-mockable
Works like LWP::UserAgent::Mockable. Set the LWP_UA_MOCK environment variable to 'playback', 'record', or 'passthrough', and the LWP_UA_MOCK_FILE environment variable to the recording file.
File to record to / play back from.
What to do on an unexpected request. One of:
-
exception
Throw an exception (i.e. die).
-
null
Return a response with empty content
-
fallback
Process the request as if this instance were in "passthrough" mode and perform the HTTP request normally.
Request header names to ignore when comparing a request made with this class to a stored request in playback mode. Specify 'all' to remove any headers from consideration. By default, the 'Connection', 'Host', 'Content-Length', and 'User-Agent' headers are ignored.
Ignore the request body entirely when comparing a request made with this class to a stored request in playback mode.
Ignore the userinfo portion of the request URL's when comparing a request to a potential counterpart in playback mode.
Optional subref. This is for when the requests require a more nuanced comparison (although it will be used in conjunction with the previous attributes).
The subref takes two parameters: the current Mojo::Message::Request and the recorded one. The subref should modify these request objects in-place so that they match each other for the parts where your code doesn't care, e.g. set an id or timestamp to the same value in both requests.
The return value is ignored, so a typical subref to ignore differences in any numerical id parts of the query path could look like this
request_normalizer => sub {
my ($req, $recorded_req) = @_;
for ($req, $recorded_req) {
$_->url->path( $_->url->path =~ s|/\d+\b|/123|gr );
}
},
In record mode, save the transaction cache to the file specified by "file" for later playback.
For the life of a given instance of this class, all transactions made using that instance will be serialized and stored in memory. When the instance goes out of scope, or at any time "save" is called, the transaction cache will be written to the file specfied by "file" in JSON format. Transactions are stored in the cache in the order they were made.
The file's contents are pretty-printed and canonicalized (ie hash keys are sorted) so that mocks are easy to read and diffs are minimized.
When this class is instantiated, the instance will read the transaction cache from the file specified by "file". When a request is first made using the instance, if the request matches that of the first transaction in the cache, the request URL will be rewritten to that of the local host, and the response from the first stored transaction will be returned to the caller. Each subsequent request will be handled similarly, and requests must be made in the same order as they were originally made, i.e. if orignally the request order was A, B, C, with responses A', B', C', requests in order A, C, B will NOT return responses A', C', B'. Request A will correctly return response A', but request C will trigger an error (behavior configurable by the "unrecognized" option).
Before comparing the current request with the recorded one, the requests are normalized using the subref in the request_normalizer attribute. The default is no normalization. See above for how to use it.
Two requests are considered to be equivalent if they have the same URL (order of query parameters notwithstanding), the same body content, and the same headers.
You may also exclude headers from consideration by means of the "ignore_headers" attribute. Or, you may excluse the request body from consideration by means of the "ignore_body" attribute.
The playback file generated by this module is unencrypted JSON. Treat the playback file as if its contents were being transmitted over an unsecured channel.
Using this module against a local app, e.g.:
my $app = Mojolicious->new;
...
my $ua = Mojo::UserAgent::Mockable->new;
$ua->server->app($app);
Doesn't work, because in playback mode, requests are served from an internal Mojolicious instance. So if you blow that away, the thing stops working, natch. You should instead instantiate Mojo::Server::Daemon and connect to the app via the server's URL, like so:
use Mojo::Server::Daemon;
use Mojo::IOLoop;
my $app = Mojolicious->new;
$app->routes->any( ... );
my $daemon = Mojo::Server::Daemon->new(
app => $app,
ioloop => Mojo::IOLoop->singleton,
silent => 1,
);
my $listen = q{http://127.0.0.1};
$daemon->listen( [$listen] )->start;
my $port = Mojo::IOLoop->acceptor( $daemon->acceptors->[0] )->port;
my $url = Mojo::URL->new(qq{$listen:$port})->userinfo('joeblow:foobar');
my $output_file = qq{/path/to/file.json};
my $mock = Mojo::UserAgent::Mockable->new(ioloop => Mojo::IOLoop->singleton, mode => 'record', file => $output_file);
my $tx = $mock->get($url);
You will often see tests written using Mojolicious::Lite like so:
use Mojolicious::Lite;
get '/' => sub { ... };
post '/foo' => sub { ... };
And then, further down:
my $ua = Mojo::UserAgent->new;
is( $ua->get('/')->res->text, ..., 'Text OK' );
Or:
use Test::Mojo;
my $t = Test::Mojo->new;
$t->get_ok('/')->status_is(200)->text_is( ... );
And this is all fine. Where it stops being fine is when you have Mojo::UserAgent::Mockable on board:
use Mojolicious::Lite;
get '/' => sub { ... };
post '/foo' => sub { ... };
use Test::Mojo;
my $t = Test::Mojo->new;
my $mock = Mojo::UserAgent::Mockable->new( mode => 'playback', file => ... );
$t->get_ok('/')->status_is(200)->text_is( ... );
Mojolicious::Lite will replace the current UA's internal application server's application instance ("app" in Mojo::UserAgent::Server) with the Mojolicious::Lite application. This will break the playback functionality, as this depends on a custom Mojolicious application internal to the module. Instead, define your application in a separate package (not necessarily a separate file), like so:
package MyApp;
use Mojolicious::Lite;
get '/' => sub { ... };
post '/foo' => sub { ... };
# Actual test application
package main;
use Mojo::UserAgent::Mockable;
use Mojo::Server::Daemon;
use Mojo::IOLoop;
use Test::Mojo;
$app->routes->get('/' => sub { ... });
$app->routes->post('/foo' => sub { ... });
my $daemon = Mojo::Server::Daemon->new(
app => $app,
ioloop => Mojo::IOLoop->singleton,
silent => 1,
);
my $listen = q{http://127.0.0.1};
$daemon->listen( [$listen] )->start;
my $port = Mojo::IOLoop->acceptor( $daemon->acceptors->[0] )->port;
my $url = Mojo::URL->new(qq{$listen:$port})->userinfo('joeblow:foobar');
my $mock = Mojo::UserAgent::Mockable->new(ioloop => Mojo::IOLoop::singleton, mode => playback, file => ... );
my $t = Test::Mojo->new;
$t->ua($mock);
$mock->get_ok($url->clone->path('/'))->status_is(200)->text_is( ... );
You can also do the following (as seen in t/030_basic_authentication.t):
use Mojolicious;
use Mojo::Server::Daemon;
use Mojo::IOLoop;
my $app = Mojolicious->new;
$app->routes->get('/' => sub { ... });
$app->routes->post('/foo' => sub { ... });
my $daemon = Mojo::Server::Daemon->new(
app => $app,
ioloop => Mojo::IOLoop->singleton,
silent => 1,
);
my $listen = q{http://127.0.0.1};
$daemon->listen( [$listen] )->start;
my $port = Mojo::IOLoop->acceptor( $daemon->acceptors->[0] )->port;
my $url = Mojo::URL->new(qq{$listen:$port})->userinfo('joeblow:foobar');
my $mock = Mojo::UserAgent::Mockable->new(ioloop => Mojo::IOLoop::singleton, mode => playback, file => ... );
my $t = Test::Mojo->new;
$t->ua($mock);
$t->get_ok('/')->status_is(200)->content_is( ... );
The following transaction level events will not be emitted during playback:
- pre_freeze
- post_freeze
- resume
-
Mojo::UserAgent The class being mocked (but not derided, because the whole Mojo thing is really quite clever)
-
Mojo::Transaction::HTTP Where the magic happens
Mike Eve https://github.com/ungrim97
Phineas J. Whoopee https://github.com/antoniel123
Marc Murray https://github.com/marcmurray
Steve Wagner <truroot at gmail.com>
Joel Berger <joel.a.berger at gmail.com>
Dan Book <grinnz at grinnz.com>
Stefan Adams <[email protected]>
Mohammad Anwar [email protected]
Johan Lindstrom [email protected]
David Cantrell [email protected]
Everyone on #mojo on irc.perl.org
Kit Peters [email protected]
This software is copyright (c) 2021 by Kit Peters.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.