NAME
PawsX::FakeImplementation::Instance - A Paws extension to help you write fake AWS services
SYNOPSIS
use Paws;
use Paws::Net::MultiplexCaller;
use PawsX::FakeImplementation::Instance;
my $paws = Paws->new(
config => {
caller => Paws::Net::MultiplexCaller->new(
caller_for => {
SQS => PawsX::FakeImplementation::Instance->new(
api_class => 'FakeSQS',
),
}
),
}
);
my $sqs = $paws->service('SQS', region => 'test');
my $new_queue = $sqs->CreateQueue(QueueName => 'MyQueue');
# the FakeSQS implementation has returned a $new_queue object just
# like SQS would:
# $new_queue->QueueUrl eq 'http://sqs.fake.amazonaws.com/123456789012/MyQueue'
my $qurl = $result->QueueUrl;
my $sent_mess = $sqs->SendMessage(MessageBody => 'Message 1', QueueUrl => $new_queue->QueueUrl);
# $sent_mess->MessageId has a unique id
my $rec_mess = $sqs->ReceiveMessage(QueueUrl => $qurl);
# $rec_mess->Messages->[0]->Body eq 'Message 1'DESCRIPTION
When working heavily with AWS services you will sometimes have special needs:
- Working on a plane (or in situations with limited connectivity)
- Testing your application
- Generating faults
PawsX::FakeImplementation::Instance will help you create fake implementations for any service you want. You will be able to emulate any service of your choice, and implement the behaviour you need to be tested.
PawsX::FakeImplementation::Instance teams up with Paws::Net::MultiplexCaller to route the appropiate service calls to the appropiate fake implementation. See Paws::Net::MultiplexCaller for more info
Creating a fake implementation
PawsX::FakeImplementation::Instance defines an interface between the fake implementations and Paws so that it's easy to write these fake implementations. Here's a guide by example to do it:
Create your fake implementation class
We start out creating a new class for our fake service:
package My::Fake::SQS;
use Moose;
1;Be careful with namespacing: take into account that your fake implementation could be partial (not a full emulation of the service), or your fake could have specialized behaviour like:
- Only implementing a subset of calls
- Only implementing partial behaviour for some calls (feature incomplete)
- Implements some type of failure mode (fails one of every 10 calls to the service)
So please try to name your fakes accordingly: My::Fake::BasicSQS, My::Fake::SQS::OutOfOrder, My::FakeSQS::OnlyAdministrativeCalls, My::FakeSQS::FailSomeCalls
If you are going to write a generic fake, trying to closely emulate the AWS service, you can use the PawsX::FakeService::SERVICE_NAME namespace.
Please have the behaviour of these generic fakes well tested and be willing to accept contributions from third parties to these fakes, as people will probably turn to those implementations by default to test services. Please document any already known differences between the real service and the fake service.
Write a fake method
Just create a sub named like the method you want to fake in your fake service class. It will receive an object with the parameters that were passed to the service:
sub CreateQueue {
my ($self, $params) = @_;
# $params->QueueName holds what the user passed to
# $sqs->CreateQueue(QueueName => '...');
return { QueueUrl => 'http://myqueue' };
}The $params object in this case is a Paws::SQS::CreateQueue object (that represents the parameters to the CreateQueue call.
Return values
The return of CreateQueue is a hashref that contains the attributes for inflating a Paws::SQS::CreateQueueResult. PawsX::FakeImplementation::Instance will convert the hashref to the appropiate return object that the calling code is expecting.
sub CreateQueue {
return { QueueUrl => 'http://myqueue' };
}from the fake implementation will be received in the calling side as always:
my $return = $sqs->CreateQueue(QueueName => 'x');
print $return->QueueUrl; # http://myqueueControlled exceptions
If the code inside a fake implementation throws or returns a Paws::Exception, the "user code" will recieve the Paws::Exception just like if Paws had generated it.
sub CreateQueue {
Paws::Exception->throw(message => 'The name is duplicate', code => 'DuplicateName');
}This helps emulate error conditions just like Paws/AWS returns them
Uncontrolled exceptions
If the code inside a fake implementation dies, PawsX::FakeImplementation::Instance will wrap it inside a generic Paws::Exception object with code 'InternalError' and the exception as the message. Paws' contract with the outside world is to throw Paws::Exception objects in case of problems, so PawsX::FakeImplementation::Instance tries to not bubble non-Paws-compliant exceptions.
Instance Storage
PawsX::FakeImplementation::Instance instances your object one time only, and after that routes method calls to your object. This lets you use an attribute to store data for the lifetime of your object, and use it as "storage". A queue service, for example could use
has _queue => (is => 'ro', isa => 'ArrayRef');as storage for the messages it enqueues. Every call to the fake services methods will see $self->_queue, and be able to manipulate it:
sub ReceiveMessage {
my ($self, $params) = @_;
my $message = pop @{ $self->_queue };
return { Messages => $message };
} Externally configurable attributes
If you want your fake service to be configurable in some way, you can specify an attribute in your fake service class.
package My::Fake::FailingSQS;
use Moose;
has failing_call_ratio => (is => 'ro', isa => 'Num', default => 0.5);
sub CreateQueue {
my ($self, $params) = @_;
die "Strange error" if (rand() < $self->failing_call_ratio);
}
1;The user of the fake service can then initialize it in the following way:
my $paws = Paws->new(
config => {
caller => Paws::Net::MultiplexCaller->new(
caller_for => {
SQS => PawsX::FakeImplementation::Instance->new(
api_class => 'My::Fake::FailingSQS',
params => {
failing_call_ratio => 1 # all calls fail
}
),
}
),
}
);It's recommended that your attribute either has a default (for easy usage), or declares itself as required as to guide the consumer of the fake service what parameters need to be passed.
AUTHOR
Jose Luis Martinez
CPAN ID: JLMARTIN
CAPSiDE
jlmartinez@capside.comSEE ALSO
https://github.com/pplu/aws-sdk-perl
BUGS and SOURCE
The source code is located here: https://github.com/pplu/pawsx-fakeimplementation-instance
Please report bugs to: https://github.com/pplu/pawsx-fakeimplementation-instance/issues
COPYRIGHT and LICENSE
Copyright (c) 2017 by CAPSiDE
This code is distributed under the Apache 2 License. The full text of the license can be found in the LICENSE file included with this module.