##########
Webservice
##########


****
NAME
****


Kernel::System::UnitTest::Webservice - web service lib


********
SYNOPSIS
********


All web service functions


****************
PUBLIC INTERFACE
****************


new()
=====


create an object


.. code-block:: perl

     use Kernel::System::ObjectManager;
     local $Kernel::OM = Kernel::System::ObjectManager->new();
     my $UnitTestWebserviceObject = $Kernel::OM->Get('Kernel::System::UnitTest::Webservice');



Process()
=========


Simulates an incoming web service call to test operations and the mapping.


.. code-block:: perl

     my $Response = $UnitTestWebserviceObject->Process(
         UnitTestObject => $Self,
         Webservice     => 'Name123', # or
         WebserviceID   => 123,
         Operation      => 'DesiredOperation',
         Payload        => {
             # ...
         },
         Response => {               # optional, you can validate the response manually in the unit test via $Self->IsDeeply()
             Success      => 1,
             ErrorMessage => '',
             Data         => {
                # ...
             },
         }
     );
 
     my $Response = {
         Success      => 1,
         ErrorMessage => '',
         Data         => {
             # ...
         },
     };



Mock()
======


Mocks all outgoing requests to a given mapping.


.. code-block:: perl

     my $Result = $UnitTestWebserviceObject->Mock(
         InvokerName123 => [
             {
                 Data => {
                     OutgoingData => 'Value'
                 },
                 Result => {
                     Success      => 1,
                     ErrorMessage => '',
                     Data         => {
                         YAY => 'so true',
                     },
                 }
             },
             # ...
         ],
         # ...
     );
 
 
     Now you can use the regular framework requester object to perform this request like:
 
     my $RequesterObject = $Kernel::OM->Get('Kernel::GenericInterface::Requester');
 
     my $Result = $RequesterObject->Run(
         WebserviceID => 1,                      # ID of the configured remote web service to use
         Invoker      => 'InvokerName123',       # Name of the Invoker to be used for sending the request
         Data         => {                       # Data payload for the Invoker request (remote web service)
             OutgoingData => 'Value'
         },
     );
 
     $Result = {
         Success => 1,
         Data    => {
             YAY => 'so true',
         },
     };



MockFromFile()
==============


Loads a mapping from JSON file placed in 'var/mocks/' in the
Webservice sub directory named as the Invoker like e.g.:
'var/mocks/ExampleWebservice/SomeInvoker.json'


.. code-block:: perl

     $UnitTestWebserviceObject->MockFromFile(
         Webservice => 'ExampleWebservice',
         Invoker    => 'SomeInvoker',
         Data       => {
 
         }
     );
 
     $UnitTestWebserviceObject->MockFromFile(
         Location => $ConfigObject->Get('Home') . "/misc/mocks/WebserviceName/SomeInvoker.json";
         Invoker    => 'SomeInvoker',
         Data       => {
 
         }
     );



Result()
========


Returns the result of all requests since beginning or the last $UnitTestWebserviceObject->Result() call.
Result cache will be cleared.


.. code-block:: perl

     my $Result = $UnitTestWebserviceObject->Result();
 
     $Result = [
         {
             Success      => 0,
             ErrorMessage => "Can't find Mock data matching the given request Data structure.",
             Invoker      => 'UserDataGet',
             Data         => {
                 Foo => 'Bar',
             },
         },
         {
             Success => 1,
             Invoker => 'Name',
             Data    => {
                 UserID => 'han',
             },
             Result => {
                 Success => 1,
                 Data    => {
                     UserName => 'Han Solo',
                 }
             },
             ResultCounter => 3,
         },
         # ...
     ];



ValidateResult()
================


Processes the results of expected mocked web service calls.
If no web service call was mocked, an error will be output.


.. code-block:: perl

     my $Result = $UnitTestWebserviceObject->ValidateResult(
         UnitTestObject => $Self,
         RequestCount   => 1, # default, defines the number of requests that should have been processed
     );
 
     $Result = [
         {
             Success      => 0,
             ErrorMessage => "Can't find Mock data matching the given request Data structure.",
             Invoker      => 'UserDataGet',
             Data         => {
                 Foo => 'Bar',
             },
         },
         {
             Success => 1,
             Invoker => 'Name',
             Data    => {
                 UserID => 'han',
             },
             Result => {
                 Success => 1,
                 Data    => {
                     UserName => 'Han Solo',
                 }
             },
             ResultCounter => 3,
         },
         # ...
     ];



SchedulerRunAll()
=================


Executes all asynchronous task handler tasks.


.. code-block:: perl

     my $Success = $UnitTestWebserviceObject->SchedulerRunAll(
         UnitTestObject => $Self,
     );
 
     my $Success = $UnitTestWebserviceObject->SchedulerRunAll(
         UnitTestObject => $Self,
         Type           => 'AsynchronousExecutor', # optional, default is 'GenericInterface'
     );


Returns:


.. code-block:: perl

     my $Success = 1;



SchedulerCleanUp()
==================


Cleans up all tasks for the scheduler.


.. code-block:: perl

     my $Success = $UnitTestWebserviceObject->SchedulerCleanUp(
         UnitTestObject => $Self,
     );
 
     my $Success = $UnitTestWebserviceObject->SchedulerCleanUp(
         UnitTestObject => $Self,
         Type           => 'AsynchronousExecutor', # optional, default is 'GenericInterface'
     );


Returns:


.. code-block:: perl

     my $Success = 1;



OperationFunctionCall()
=======================


Initializes an operation to test specific functions of an operation.


.. code-block:: perl

     my $Success = $UnitTestWebserviceObject->OperationFunctionCall(
         Webservice    => 'webservice-name',
         Operation     => 'operation-name',
         Function      => 'function',
         Data          => {},
     );
 
     my $Success = $UnitTestWebserviceObject->OperationFunctionCall(
         Webservice           => 'webservice-name',
         Operation            => 'operation-name',
         Function             => 'function',
         Data                 => {},
         ObjectModifyFunction => sub {
             my (%Params) = @_;
 
             $Params{Object}->{BackendObject}->{MessageName} = 'SEND_UPDATE';
 
             return 1;
         },
     );


Returns:


.. code-block:: perl

     my $Success = 1;



InvokerFunctionCall()
=====================


Initialize an invoker to test specific functions of an invoker.


.. code-block:: perl

     my $Success = $UnitTestWebserviceObject->InvokerFunctionCall(
         Webservice => 'webservice-name',
         Invoker    => 'invoker-name',
         Function   => 'function',
         Data       => {},
     );
 
     my $Success = $UnitTestWebserviceObject->InvokerFunctionCall(
         Webservice => 'webservice-name',
         Invoker    => 'invoker-name',
         Function   => 'function',
         Data       => {},
         ObjectModifyFunction => sub {
             my (%Params) = @_;
 
             $Params{Object}->{BackendObject}->{MessageName} = 'SEND_UPDATE';
 
             return 1;
         },
     );


Returns:


.. code-block:: perl

     my $Success = 1;



_WebserviceObjectModify()
=========================


Internal function which will be used for OperationFunctionCall and InvokerFunctionCall
to modify the object values of the initialized web service invoker or operation object.


.. code-block:: perl

     my $Success = $UnitTestWebserviceObject->_WebserviceObjectModify(
         Object               => \$OperationObject,
         ObjectModifyFunction => sub {
             my (%Params) = @_;
 
             $Params{Object}->{BackendObject}->{MessageName} = 'SEND_UPDATE';
 
             return 1;
         },
     );


Returns:


.. code-block:: perl

     my $Success = 1;



CreateGenericInterfaceMappingObject()
=====================================


Creates a mapping object to be used within unit tests.


.. code-block:: perl

     my $MappingObject = $UnitTestWebserviceObject->CreateGenericInterfaceMappingObject(
         UnitTestObject    => $Self,
         WebserviceName    => 'MyWebservice',
         CommunicationType => 'Provider',
         MappingConfig     => {
             Type => 'MyMapping', # name of mapping module
             Config => {
                 # ...
             },
         },
     );



_RedefineTransport()
====================


Redefines the functions of the transport object to handle tests and provide the results.


.. code-block:: perl

     $Object->_RedefineTransport();