Util\Timing: add tests

Includes minor fixes to the class documentation.

src/Util/Timing.php

@@ -13,7 +13,7 @@ class Timing
 {
 
     /**
-     * The start time of the run.
+     * The start time of the run in microseconds.
      *
      * @var float
      */
@@ -43,7 +43,7 @@ public static function startTiming()
     /**
      * Get the duration of the run up to "now".
      *
-     * @return float Duration in microseconds.
+     * @return float Duration in milliseconds.
      */
     public static function getDuration()
     {
@@ -58,9 +58,9 @@ public static function getDuration()
 
 
     /**
-     * Convert a duration in microseconds to a human readable duration string.
+     * Convert a duration in milliseconds to a human readable duration string.
      *
-     * @param float $duration Duration in microseconds.
+     * @param float $duration Duration in milliseconds.
      *
      * @return string
      */

tests/Core/Util/Timing/GetHumanReadableDurationTest.php

@@ -0,0 +1,114 @@
+<?php
+/**
+ * Tests for the \PHP_CodeSniffer\Util\Timing::getHumanReadableDuration() method.
+ *
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
+ * @copyright 2024 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\Util\Timing;
+
+use PHP_CodeSniffer\Util\Timing;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for the \PHP_CodeSniffer\Util\Timing::getHumanReadableDuration() method.
+ *
+ * @covers \PHP_CodeSniffer\Util\Timing::getHumanReadableDuration
+ */
+final class GetHumanReadableDurationTest extends TestCase
+{
+
+
+    /**
+     * Test the method.
+     *
+     * @param int|float $duration A duration in milliseconds.
+     * @param string    $expected The expected human readable string.
+     *
+     * @dataProvider dataGetHumanReadableDuration
+     *
+     * @return void
+     */
+    public function testGetHumanReadableDuration($duration, $expected)
+    {
+        $this->assertSame($expected, Timing::getHumanReadableDuration($duration));
+
+    }//end testGetHumanReadableDuration()
+
+
+    /**
+     * Data provider.
+     *
+     * @return array<string, array<string, int|float|string>>
+     */
+    public static function dataGetHumanReadableDuration()
+    {
+        return [
+            'Duration: 0'                                  => [
+                'duration' => 0,
+                'expected' => '0ms',
+            ],
+            'Duration: 13 milliseconds'                    => [
+                'duration' => 13.232101565,
+                'expected' => '13ms',
+            ],
+            'Duration: 14 milliseconds'                    => [
+                'duration' => 13.916015625,
+                'expected' => '14ms',
+            ],
+            'Duration: 999 milliseconds'                   => [
+                'duration' => 999.2236,
+                'expected' => '999ms',
+            ],
+            'Duration: 999+ milliseconds'                  => [
+                'duration' => 999.89236,
+                'expected' => '1000ms',
+            ],
+            'Duration: 1 second'                           => [
+                'duration' => 1000,
+                'expected' => '1000ms',
+            ],
+            'Duration: slightly more than 1 second'        => [
+                'duration' => 1001.178215,
+                'expected' => '1 secs',
+            ],
+            'Duration: just under a 1 minute'              => [
+                'duration' => 59999.3851,
+                'expected' => '60 secs',
+            ],
+            'Duration: exactly 1 minute'                   => [
+                'duration' => 60000,
+                'expected' => '60 secs',
+            ],
+            'Duration: slightly more than 1 minute'        => [
+                'duration' => 60001.7581235,
+                'expected' => '1 mins, 0 secs',
+            ],
+            'Duration: 1 minute, just under half a second' => [
+                'duration' => 60499.83639,
+                'expected' => '1 mins, 0.5 secs',
+            ],
+            'Duration: 1 minute, just over half a second'  => [
+                'duration' => 60501.961238,
+                'expected' => '1 mins, 0.5 secs',
+            ],
+            'Duration: 1 minute, 1 second'                 => [
+                'duration' => 61000,
+                'expected' => '1 mins, 1 secs',
+            ],
+            'Duration: exactly 1 hour'                     => [
+                'duration' => 3600000,
+                'expected' => '60 mins, 0 secs',
+            ],
+            'Duration: 89.4 mins'                          => [
+                'duration' => 5364000,
+                'expected' => '89 mins, 24 secs',
+            ],
+        ];
+
+    }//end dataGetHumanReadableDuration()
+
+
+}//end class

tests/Core/Util/Timing/TimingTest.php

@@ -0,0 +1,123 @@
+<?php
+/**
+ * Tests for the \PHP_CodeSniffer\Util\Timing class.
+ *
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
+ * @copyright 2024 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\Util\Timing;
+
+use PHP_CodeSniffer\Util\Timing;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for the \PHP_CodeSniffer\Util\Timing class.
+ *
+ * {@internal These tests need to run in separate processes as the Timing class uses static properties
+ * to keep track of the start time and whether or not the runtime has been printed and these
+ * can't be unset/reset once set.}
+ *
+ * @covers \PHP_CodeSniffer\Util\Timing
+ *
+ * @runTestsInSeparateProcesses
+ * @preserveGlobalState         disabled
+ */
+final class TimingTest extends TestCase
+{
+
+
+    /**
+     * Verify that getDuration() returns 0 when the timer wasn't started.
+     *
+     * @return void
+     */
+    public function testGetDurationWithoutStartReturnsZero()
+    {
+        $this->assertSame(0, Timing::getDuration());
+
+    }//end testGetDurationWithoutStartReturnsZero()
+
+
+    /**
+     * Verify that getDuration() returns 0 when the timer wasn't started.
+     *
+     * @return void
+     */
+    public function testGetDurationWithStartReturnsMilliseconds()
+    {
+        Timing::startTiming();
+        usleep(1500);
+        $duration = Timing::getDuration();
+
+        $this->assertTrue(is_float($duration));
+        $this->assertGreaterThan(1, $duration);
+        $this->assertLessThan(15, $duration);
+
+    }//end testGetDurationWithStartReturnsMilliseconds()
+
+
+    /**
+     * Verify that printRunTime() doesn't print anything if the timer wasn't started.
+     *
+     * @return void
+     */
+    public function testTimeIsNotPrintedIfTimerWasNeverStarted()
+    {
+        $this->expectOutputString('');
+        Timing::printRunTime();
+
+    }//end testTimeIsNotPrintedIfTimerWasNeverStarted()
+
+
+    /**
+     * Verify that printRunTime() doesn't print anything if the timer wasn't started.
+     *
+     * @return void
+     */
+    public function testTimeIsNotPrintedIfTimerWasNeverStartedEvenWhenForced()
+    {
+        $this->expectOutputString('');
+        Timing::printRunTime(true);
+
+    }//end testTimeIsNotPrintedIfTimerWasNeverStartedEvenWhenForced()
+
+
+    /**
+     * Verify that printRunTime() when called multiple times only prints the runtime information once.
+     *
+     * @return void
+     */
+    public function testTimeIsPrintedOnlyOnce()
+    {
+        $this->expectOutputRegex('`^Time: [0-9]+ms; Memory: [0-9\.]+MB'.PHP_EOL.PHP_EOL.'$`');
+
+        Timing::startTiming();
+        usleep(2000);
+        Timing::printRunTime();
+        Timing::printRunTime();
+        Timing::printRunTime();
+
+    }//end testTimeIsPrintedOnlyOnce()
+
+
+    /**
+     * Verify that printRunTime() when called multiple times prints the runtime information multiple times if forced.
+     *
+     * @return void
+     */
+    public function testTimeIsPrintedMultipleTimesOnlyIfForced()
+    {
+        $this->expectOutputRegex('`^(Time: [0-9]+ms; Memory: [0-9\.]+MB'.PHP_EOL.PHP_EOL.'){3}$`');
+
+        Timing::startTiming();
+        usleep(2000);
+        Timing::printRunTime(true);
+        Timing::printRunTime(true);
+        Timing::printRunTime(true);
+
+    }//end testTimeIsPrintedMultipleTimesOnlyIfForced()
+
+
+}//end class