test: add SQL equality assertion helper

- Add assertSqlEquals() to CIUnitTestCase
- Document the helper in the testing guide
- Use the helper in representative Query Builder tests

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/Test/CIUnitTestCase.php

@@ -501,6 +501,14 @@ public function assertCloseEnoughString($expected, $actual, string $message = ''
         return null;
     }
 
+    /**
+     * Asserts that two SQL strings are the same, ignoring newlines in the actual SQL.
+     */
+    public function assertSqlEquals(string $expected, string $actual, string $message = ''): void
+    {
+        $this->assertSame($expected, str_replace("\n", ' ', $actual), $message);
+    }
+
     // --------------------------------------------------------------------
     // Utility
     // --------------------------------------------------------------------

tests/system/Database/Builder/DeleteTest.php

@@ -46,7 +46,7 @@ public function testDelete(): void
             ],
         ];
 
-        $this->assertSame($expectedSQL, str_replace("\n", ' ', $answer));
+        $this->assertSqlEquals($expectedSQL, $answer);
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 

tests/system/Database/Builder/PrefixTest.php

@@ -51,7 +51,7 @@ public function testPrefixesSetOnTableNamesWithWhereClause(): void
 
         $builder->where($where);
 
-        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+        $this->assertSqlEquals($expectedSQL, $builder->getCompiledSelect());
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 
@@ -64,7 +64,7 @@ public function testPrefixesSetOnTableNamesWithWhereColumnClause(): void
 
         $builder->whereColumn('users.created_at <', 'users.updated_at');
 
-        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+        $this->assertSqlEquals($expectedSQL, $builder->getCompiledSelect());
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 
@@ -86,7 +86,7 @@ public function testPrefixesSetOnTableNamesWithWhereBetweenClause(): void
 
         $builder->whereBetween('users.created_at', [1, 10]);
 
-        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+        $this->assertSqlEquals($expectedSQL, $builder->getCompiledSelect());
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 

tests/system/Test/TestCaseTest.php

@@ -93,4 +93,15 @@ public function testCloseEnoughStringBadLength(): void
         $result = $this->assertCloseEnoughString('apples & oranges', 'apples');
         $this->assertFalse($result, 'Different string lengths should have returned false');
     }
+
+    public function testAssertSqlEqualsIgnoresNewlinesInActualSql(): void
+    {
+        $expected = 'SELECT * FROM "jobs" WHERE "id" = 1';
+        $actual   = <<<'SQL'
+            SELECT * FROM "jobs"
+            WHERE "id" = 1
+            SQL;
+
+        $this->assertSqlEquals($expected, $actual);
+    }
 }

user_guide_src/source/changelogs/v4.8.0.rst

@@ -213,6 +213,8 @@ Commands
 Testing
 =======
 
+- Added ``assertSqlEquals()`` to ``CIUnitTestCase`` to compare generated SQL while ignoring newlines in the actual SQL.
+
 Database
 ========
 

user_guide_src/source/testing/overview.rst

@@ -202,6 +202,13 @@ between expected and actual time, formatted as strings, is within the prescribed
 
 The above test will allow the actual time to be either 660 or 661 seconds.
 
+assertSqlEquals($expected, $actual, $message = '')
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Asserts that two SQL strings are the same, ignoring newlines in the actual SQL:
+
+.. literalinclude:: overview/023.php
+
 Accessing Protected/Private Properties
 --------------------------------------
 

user_guide_src/source/testing/overview/023.php

@@ -0,0 +1,6 @@
+<?php
+
+$expected = 'SELECT * FROM "jobs" WHERE "id" = 1';
+$actual   = $builder->where('id', 1)->getCompiledSelect();
+
+$this->assertSqlEquals($expected, $actual);