Merge pull request #8251 from kenjis/docs-testing-and-time

docs: add missing Time::setTestNow()

Author: kenjis

user_guide_src/source/testing/overview.rst

@@ -267,6 +267,23 @@ component name:
 
 .. note:: All component Factories are reset by default between each test. Modify your test case's ``$setUpMethods`` if you need instances to persist.
 
+Testing and Time
+================
+
+Testing time-dependent code can be challenging. However, when using the
+:doc:`Time <../libraries/time>` class, the current time can be fixed or changed
+at will during testing.
+
+Below is a sample test code that fixes the current time:
+
+.. literalinclude:: overview/021.php
+
+You can fix the current time with the ``Time::setTestNow()`` method.
+Optionally, you can specify a locale as the second parameter.
+
+Don't forget to reset the current time after the test with calling it without
+parameters.
+
 .. _testing-cli-output:
 
 Testing CLI Output

user_guide_src/source/testing/overview/021.php

@@ -0,0 +1,24 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+use CodeIgniter\Test\CIUnitTestCase;
+
+final class TimeDependentCodeTest extends CIUnitTestCase
+{
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+
+        // Reset the current time.
+        Time::setTestNow();
+    }
+
+    public function testFixTime(): void
+    {
+        // Fix the current time to "2023-11-25 12:00:00".
+        Time::setTestNow('2023-11-25 12:00:00');
+
+        // This assertion always passes.
+        $this->assertSame('2023-11-25 12:00:00', (string) Time::now());
+    }
+}