NN2024010801/vendor/ramsey/uuid/docs/testing.rst

.. _testing:

==================
Testing With UUIDs
==================

One problem with the use of ``final`` is the inability to create a `mock object`_
to use in tests. However, the following techniques should help with testing.

.. tip::

    To learn why ramsey/uuid uses ``final``, take a look at :ref:`faq.final`.


.. _testing.inject:

Inject a UUID of a Specific Type
--------------------------------

Let's say we have a method that uses a type hint for :php:class:`UuidV1
<Ramsey\\Uuid\\Rfc4122\\UuidV1>`.

.. code-block:: php

    public function tellTime(UuidV1 $uuid): string
    {
        return $uuid->getDateTime()->format('Y-m-d H:i:s');
    }

Since this method uses UuidV1 as the type hint, we're not able to pass another
object that implements UuidInterface, and we cannot extend or mock UuidV1, so
how do we test this?

One way is to use :php:meth:`Uuid::uuid1() <Ramsey\\Uuid\\Uuid::uuid1>` to
create a regular UuidV1 instance and pass it.

.. code-block:: php

    public function testTellTime(): void
    {
        $uuid = Uuid::uuid1();
        $myObj = new MyClass();

        $this->assertIsString($myObj->tellTime($uuid));
    }

This might satisfy our testing needs if we only want to assert that the method
returns a string. If we want to test for a specific string, we can do that, too,
by generating a UUID ahead of time and using it as a known value.

.. code-block:: php

    public function testTellTime(): void
    {
        // We generated this version 1 UUID ahead of time and know the
        // exact date and time it contains, so we can use it to test the
        // return value of our method.
        $uuid = Uuid::fromString('177ef0d8-6630-11ea-b69a-0242ac130003');
        $myObj = new MyClass();

        $this->assertSame('2020-03-14 20:12:12', $myObj->tellTime($uuid));
    }

.. note::

    These examples assume the use of `PHPUnit`_ for tests. The concepts will
    work no matter what testing framework you use.


.. _testing.static:

Returning Specific UUIDs From a Static Method
---------------------------------------------

Sometimes, rather than pass UUIDs as method arguments, we might call the static
methods on the Uuid class from inside the method we want to test. This can be
tricky to test.

.. code-block:: php

    public function tellTime(): string
    {
        $uuid = Uuid::uuid1();

        return $uuid->getDateTime()->format('Y-m-d H:i:s');
    }

We can call this in a test and assert that it returns a string, but we can't
return a specific UUID value from the static method call --- or can we?

We can do this by :ref:`overriding the default factory <customize.factory>`.

First, we create our own factory class for testing. In this example, we extend
UuidFactory, but you may create your own separate factory class for testing, as
long as you implement :php:interface:`Ramsey\\Uuid\\UuidFactoryInterface`.

.. code-block:: php

    namespace MyPackage;

    use Ramsey\Uuid\UuidFactory;
    use Ramsey\Uuid\UuidInterface;

    class MyTestUuidFactory extends UuidFactory
    {
        public $uuid1;

        public function uuid1($node = null, ?int $clockSeq = null): UuidInterface
        {
            return $this->uuid1;
        }
    }

Now, from our tests, we can replace the default factory with our new factory,
and we can even change the value returned by the :php:meth:`uuid1()
<Ramsey\\Uuid\\UuidFactoryInterface::uuid1>` method for our tests.

.. code-block:: php

    /**
     * @runInSeparateProcess
     * @preserveGlobalState disabled
     */
    public function testTellTime(): void
    {
        $factory = new MyTestUuidFactory();
        Uuid::setFactory($factory);

        $myObj = new MyClass();

        $factory->uuid1 = Uuid::fromString('177ef0d8-6630-11ea-b69a-0242ac130003');
        $this->assertSame('2020-03-14 20:12:12', $myObj->tellTime());

        $factory->uuid1 = Uuid::fromString('13814000-1dd2-11b2-9669-00007ffffffe');
        $this->assertSame('1970-01-01 00:00:00', $myObj->tellTime());
    }

.. attention::

    The factory is a static property on the Uuid class. By replacing it like
    this, all uses of the Uuid class after this point will continue to use the
    new factory. This is why we must run the test in a separate process.
    Otherwise, this could cause other tests to fail.

    Running tests in separate processes can significantly slow down your tests,
    so try to use this technique sparingly, and if possible, pass your
    dependencies to your objects, rather than creating (or fetching them) from
    within. This makes testing easier.


.. _testing.mock:

Mocking UuidInterface
---------------------

Another technique for testing with UUIDs is to mock
:php:interface:`UuidInterface <Ramsey\\Uuid\\UuidInterface>`.

Consider a method that accepts a UuidInterface.

.. code-block:: php

    public function tellTime(UuidInterface $uuid): string
    {
        return $uuid->getDateTime()->format('Y-m-d H:i:s');
    }

We can mock UuidInterface, passing that mocked value into this method. Then, we
can make assertions about what methods were called on the mock object. In the
following example test, we don't care whether the return value matches an
actual date format. What we care about is that the methods on the UuidInterface
object were called.

.. code-block:: php

    public function testTellTime(): void
    {
        $dateTime = Mockery::mock(DateTime::class);
        $dateTime->expects()->format('Y-m-d H:i:s')->andReturn('a test date');

        $uuid = Mockery::mock(UuidInterface::class, [
            'getDateTime' => $dateTime,
        ]);

        $myObj = new MyClass();

        $this->assertSame('a test date', $myObj->tellTime($uuid));
    }

.. note::

    One of my favorite mocking libraries is `Mockery`_, so that's what I use in
    these examples. However, other mocking libraries exist, and PHPUnit provides
    built-in mocking capabilities.


.. _mock object: https://en.wikipedia.org/wiki/Mock_object
.. _PHPUnit: https://phpunit.de
.. _Mockery: https://github.com/mockery/mockery