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://myqueue

Controlled 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.com

SEE ALSO

Paws

Paws::Net::MultiplexCaller

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.