######
Driver
######


****
NAME
****


Kernel::System::UnitTest::Driver - unit test file execution wrapper


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


new()
=====


create unit test driver object. Do not use it directly, instead use:


.. code-block:: perl

     my $DriverObject = $Kernel::OM->Create(
         'Kernel::System::UnitTest::Driver',
         ObjectParams => {
             Verbose => $Self->{Verbose},
             ANSI    => $Self->{ANSI},
         },
     );



Run()
=====


executes a single unit test file and provides it with an empty environment (fresh \ ``ObjectManager``\  instance).

This method assumes that it runs in a dedicated child process just for this one unit test.
This process forking is done in `Kernel::System::UnitTest`, which creates one child process per test file.

All results will be collected and written to a \ ``var/tmp/UnitTest.dump``\  file that the main process will
load to collect all results.


True()
======


test for a scalar value that evaluates to true.

Send a scalar value to this function along with the test's name:


.. code-block:: perl

     $UnitTestObject->True(1, 'Test Name');
 
     $UnitTestObject->True($ParamA, 'Test Name');


Internally, the function receives this value and evaluates it to see
if it's true, returning 1 in this case or undef, otherwise.


.. code-block:: perl

     $UnitTestObject->True(
         $TestValue,
         'Test Name',
     );



False()
=======


test for a scalar value that evaluates to false.

It has the same interface as `True()`_, but tests
for a false value instead.


.. code-block:: perl

     $UnitTestObject->False(1, 'Test Name');
 
     $UnitTestObject->False($ParamA, 'Test Name');


Internally, the function receives this value and evaluates it to see
if it's false, returning 1 in this case or undef, otherwise.


.. code-block:: perl

     $UnitTestObject->False(
         $TestValue,
         'Test Name',
     );



Is()
====


compares two scalar values for equality.

To this function you must send a pair of scalar values to compare them,
and the name that the test will take, this is done as shown in the examples
below.


.. code-block:: perl

     $UnitTestObject->Is($A, $B, 'Test Name');


Returns 1 if the values were equal, or undef otherwise.


.. code-block:: perl

     $UnitTestObject->Is(
         $ValueFromFunction,      # test data
         1,                       # expected value
         'Test Name',
     );



IsNot()
=======


compares two scalar values for inequality.

It has the same interface as `Is()`_, but tests for inequality instead.


.. code-block:: perl

     $UnitTestObject->IsNot($A, $B, 'Test Name');


Returns 1 if the values were not equal, or undef otherwise.


.. code-block:: perl

     $UnitTestObject->IsNot(
         $ValueFromFunction,      # test data
         1,                       # expected value
         'Test Name',
     );



IsDeeply()
==========


compares complex data structures for equality.

To this function you must send the references to two data structures to be compared,
and the name that the test will take, this is done as shown in the examples
below.


.. code-block:: perl

     $UnitTestObject->IsDeeply($ParamA, $ParamB, 'Test Name');


Where $ParamA and $ParamB must be references to a structure (scalar, list or hash).

Returns 1 if the data structures are the same, or undef otherwise.


.. code-block:: perl

     $UnitTestObject->IsDeeply(
         \%ResultHash,           # test data
         \%ExpectedHash,         # expected value
         'Dummy Test Name',
     );



IsNotDeeply()
=============


compares two data structures for inequality.

It has the same interface as `IsDeeply()`_, but tests for inequality instead.


.. code-block:: perl

     $UnitTestObject->IsNotDeeply($ParamA, $ParamB, 'Test Name');


Where $ParamA and $ParamB must be references to a structure (scalar, list or hash).

Returns 1 if the data structures are not the same, or undef otherwise.


.. code-block:: perl

     $UnitTestObject->IsNotDeeply(
         \%ResultHash,           # test data
         \%ExpectedHash,         # expected value
         'Dummy Test Name',
     );



AttachSeleniumScreenshot()
==========================


attach a screenshot taken during Selenium error handling. These will be sent to the server
together with the test results.


.. code-block:: perl

     $UnitTestObject->AttachSeleniumScreenshot(
         Filename => $Filename,
         Content  => $Data               # raw image data
     );



_Color()
========


this will color the given text (see Term::ANSIColor::color()) if
ANSI output is available and active, otherwise the text stays unchanged.


.. code-block:: perl

     my $PossiblyColoredText = $CommandObject->_Color('green', $Text);