From 57c92c28551cab90d0d23b3c7f41d895444777de Mon Sep 17 00:00:00 2001
From: petrdobr <dobrokhotovp@gmail.com>
Date: Wed, 29 Oct 2025 22:59:37 +0100
Subject: [PATCH] feat(assert): add `Assert::lesserThan` and
 `Assert::lesserThanOrEqual` methods

---
 src/Assert.php                               | 42 +++++++++++++++
 tests/Testo/AsserTest.php                    |  2 +
 tests/Testo/Assert/AssertLessThan.php        | 49 +++++++++++++++++
 tests/Testo/Assert/AssertLessThanOrEqual.php | 56 ++++++++++++++++++++
 4 files changed, 149 insertions(+)
 create mode 100644 tests/Testo/Assert/AssertLessThan.php
 create mode 100644 tests/Testo/Assert/AssertLessThanOrEqual.php

diff --git a/src/Assert.php b/src/Assert.php
index 7f0500a..f933892 100644
--- a/src/Assert.php
+++ b/src/Assert.php
@@ -91,6 +91,48 @@ public static function notEquals(mixed $expected, mixed $actual, string $message
             ));
     }
 
+    /**
+     * Asserts that actual value is less than the defined maximum.
+     *
+     * @param mixed $maximum The defined maximum value.
+     * @param mixed $actual The actual value to compare against the maximum value.
+     * @param string $message Short description about what exactly is being asserted.
+     * @throws AssertException when the assertion fails.
+     */
+    public static function lessThan(mixed $maximum, mixed $actual, string $message = ''): void
+    {
+        $actual < $maximum
+            ? StaticState::log('Assert `' . Support::stringify($actual) . '` is less than: `' . Support::stringify($maximum) . '`', $message)
+            : StaticState::fail(AssertException::compare(
+                $maximum,
+                $actual,
+                $message,
+                pattern: 'Failed asserting that `%2s` is less than `%1s`',
+                showDiff: false,
+            ));
+    }
+
+    /**
+     * Asserts that actual value is less than or equal to the defined maximum.
+     *
+     * @param mixed $maximum The defined maximum value.
+     * @param mixed $actual The actual value to compare against the maximum value.
+     * @param string $message Short description about what exactly is being asserted.
+     * @throws AssertException when the assertion fails.
+     */
+    public static function lessThanOrEqual(mixed $maximum, mixed $actual, string $message = ''): void
+    {
+        $actual <= $maximum
+            ? StaticState::log('Assert `' . Support::stringify($actual) . '` is less than or equal to: `' . Support::stringify($maximum) . '`', $message)
+            : StaticState::fail(AssertException::compare(
+                $maximum,
+                $actual,
+                $message,
+                pattern: 'Failed asserting that `%2s` is less than or equal to `%1s`',
+                showDiff: false,
+            ));
+    }
+
     /**
      * Asserts that the condition is true.
      *
diff --git a/tests/Testo/AsserTest.php b/tests/Testo/AsserTest.php
index 0f5bd09..17cb9b3 100644
--- a/tests/Testo/AsserTest.php
+++ b/tests/Testo/AsserTest.php
@@ -27,6 +27,8 @@ public function simpleAssertions(): void
         Assert::instanceOf(\Exception::class, new \RuntimeException());
         Assert::equals(1, '1');
         Assert::notEquals(42, 43);
+        Assert::lessThan(2, 1);
+        Assert::lessThanOrEqual(2, 1);
     }
 
     #[Test]
diff --git a/tests/Testo/Assert/AssertLessThan.php b/tests/Testo/Assert/AssertLessThan.php
new file mode 100644
index 0000000..e6514fd
--- /dev/null
+++ b/tests/Testo/Assert/AssertLessThan.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Testo\Assert;
+
+use Testo\Assert;
+use Testo\Attribute\Test;
+
+/**
+ * Assertion examples.
+ */
+final class AssertLessThan
+{
+    #[Test]
+    public function numbers(): void
+    {
+        Assert::lessThan(2, 1);
+        Assert::lessThan(1.1, 1);
+        Assert::lessThan('2', 1); //'2' coerces to 2
+    }
+
+    #[Test]
+    public function strings(): void
+    {
+        Assert::lessThan("43", "42"); // numeric strings are cast to numbers
+        Assert::lessThan("aaaa", "aaa"); // shorter string is smaller
+        Assert::lessThan("beerz", "beers"); // byte-wise comparison (first different letters are compared as byte values)
+    }
+
+    #[Test]
+    public function arrays(): void
+    {
+        Assert::lessThan([1, 2, 3], [1, 2]); // prefix rule: shorter wins
+        Assert::lessThan([1, 4], [1, 3]); // first differing element decides: 3 < 4
+        Assert::lessThan(['a' => 1, 'b' => 2, 'c' => 0], ['a' => 1, 'b' => 2]); // associative, same key order: shorter wins
+
+        // comparison of associative arrays with different keys won't work and throws AssertException:
+        // Assert::lessThan(['a' => 1, 'x' => 999], ['a' => 1, 'b' => 1]);
+    }
+
+    #[Test]
+    public function datetimes(): void
+    {
+        $max  = new \DateTimeImmutable('2025-01-02 00:00:00+00:00');
+        $actual = new \DateTimeImmutable('2025-01-01 00:00:00+00:00');
+        Assert::lessThan($max, $actual); // earlier time is smaller
+    }
+}
diff --git a/tests/Testo/Assert/AssertLessThanOrEqual.php b/tests/Testo/Assert/AssertLessThanOrEqual.php
new file mode 100644
index 0000000..dec0048
--- /dev/null
+++ b/tests/Testo/Assert/AssertLessThanOrEqual.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Testo\Assert;
+
+use Testo\Assert;
+use Testo\Attribute\Test;
+
+/**
+ * Assertion examples.
+ */
+final class AssertLessThanOrEqual
+{
+    #[Test]
+    public function numbers(): void
+    {
+        Assert::lessThanOrEqual(2, 1);
+        Assert::lessThanOrEqual(1.1, 1);
+        Assert::lessThanOrEqual('2', 1); //'1' coerces to 1
+        Assert::lessThanOrEqual('1', 1);
+    }
+
+    #[Test]
+    public function strings(): void
+    {
+        Assert::lessThanOrEqual("42", "42"); // numeric strings are cast to numbers
+        Assert::lessThanOrEqual("43", "42");
+        Assert::lessThanOrEqual("aaaa", "aaa"); // shorter string is smaller
+        Assert::lessThanOrEqual("aaa", "aaa");
+        Assert::lessThanOrEqual("beerz", "beers"); // byte-wise comparison (first different letters are compared as byte values)
+    }
+
+    #[Test]
+    public function arrays(): void
+    {
+        Assert::lessThanOrEqual([1, 2], [1, 2]); // same arrays considered equal
+        Assert::lessThanOrEqual([1, 2, 3], [1, 2]); // prefix rule: shorter wins
+        Assert::lessThanOrEqual([1, 4], [1, 3]); // first differing element decides: 3 < 4
+        Assert::lessThanOrEqual(['a' => 1, 'b' => 2, 'c' => 0], ['a' => 1, 'b' => 2]); // associative, same key order: shorter wins
+        Assert::lessThanOrEqual(['b' => 2, 'a' => 1], ['a' => 1, 'b' => 2]); // associative arrays, same elements, different order - considered equal
+
+        // comparison of associative arrays with different keys won't work and throws AssertException:
+        // Assert::lessThanOrEqual(['a' => 1, 'x' => 999], ['a' => 1, 'b' => 1]);
+    }
+
+    #[Test]
+    public function datetimes(): void
+    {
+        $max  = new \DateTimeImmutable('2025-01-02 00:00:00+00:00');
+        $actual1 = new \DateTimeImmutable('2025-01-01 00:00:00+00:00');
+        $actual2 = new \DateTimeImmutable('2025-01-02 00:00:00+00:00');
+        Assert::lessThanOrEqual($max, $actual1); // earlier time is smaller
+        Assert::lessThanOrEqual($max, $actual2); // same times are equal
+    }
+}