[3.0] Gives the existing tests the license header and the agreed docblocks

tests/AutoReview/ComposerFileTest.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2026 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 5-dev
+ */
+
 declare(strict_types=1);
 
 namespace SMF\Tests\AutoReview;
@@ -14,6 +25,13 @@ final class ComposerFileTest extends TestCase
 	 * Public methods
 	 ****************/
 
+	/**
+	 * Every Composer script has a description.
+	 *
+	 * Expected: apart from Composer's own event names, the keys of scripts in
+	 *           composer.json and the keys of scripts-descriptions are the same
+	 *           set.
+	 */
 	public function testScriptsHaveDescriptions(): void
 	{
 		$composer_json = $this->readComposerJson();
@@ -67,6 +85,12 @@ public function testScriptsHaveDescriptions(): void
 		);
 	}
 
+	/**
+	 * The platform PHP version satisfies the PHP requirement.
+	 *
+	 * Expected: Semver::satisfies() accepts config.platform.php from
+	 *           composer.json against require.php.
+	 */
 	public function testPlatformPhpVersionSatisfiesPhpRequirement(): void
 	{
 		$composer_json = $this->readComposerJson();

tests/AutoReview/ForumTest.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2026 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 5-dev
+ */
+
 declare(strict_types=1);
 
 namespace SMF\Tests\AutoReview;
@@ -17,10 +28,14 @@ class ForumTest extends TestCase
 	 ****************/
 
 	/**
-	 * Tests that every action definition has the expected structure.
+	 * Every action definition has the expected structure.
 	 *
 	 * Each action must contain a source file and a handler. The handler must
 	 * either be an ActionInterface implementation or a callable.
+	 *
+	 * Expected: each entry of Forum::$actions is a two-element list whose first
+	 *           element is a string and whose second is an ActionInterface
+	 *           class name or a callable.
 	 */
 	public function testActionDefinitions(): void
 	{
@@ -40,7 +55,10 @@ public function testActionDefinitions(): void
 	}
 
 	/**
-	 * Tests that all renamed actions point to actions that exist.
+	 * All renamed actions point to actions that exist.
+	 *
+	 * Expected: array_diff(Forum::$renamed_actions,
+	 *           array_keys(Forum::$actions)) is empty.
 	 */
 	public function testRenamedActionsExist(): void
 	{
@@ -52,7 +70,10 @@ public function testRenamedActionsExist(): void
 	}
 
 	/**
-	 * Tests that all actions excluded from logging exist.
+	 * All actions excluded from logging exist.
+	 *
+	 * Expected: array_diff_key(Forum::$unlogged_actions, Forum::$actions) is
+	 *           empty.
 	 */
 	public function testUnloggedActionsExist(): void
 	{
@@ -64,7 +85,10 @@ public function testUnloggedActionsExist(): void
 	}
 
 	/**
-	 * Tests that all actions accessible to guests exist.
+	 * All actions accessible to guests exist.
+	 *
+	 * Expected: array_diff(Forum::$guest_access_actions,
+	 *           array_keys(Forum::$actions)) is empty.
 	 */
 	public function testGuestAccessActionsExist(): void
 	{

tests/AutoReview/LicenseTest.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2026 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 5-dev
+ */
+
 declare(strict_types=1);
 
 namespace SMF\Tests\AutoReview;
@@ -52,8 +63,11 @@ class LicenseTest extends TestCase
 	 ****************/
 
 	/**
-	 * Tests that every PHP file that is not explicitly ignored has a valid
-	 * SMF license header.
+	 * Every PHP file that is not explicitly ignored has a valid SMF license
+	 * header.
+	 *
+	 * Expected: the contents of each file from getPhpFiles() match
+	 *           getLicensePattern().
 	 */
 	public function testFilesHaveValidLicense(): void
 	{
@@ -83,8 +97,14 @@ public function testFilesHaveValidLicense(): void
 	}
 
 	/**
-	 * Tests that files whose headers contain the current software version and
-	 * year use the values defined by index.php.
+	 * Files whose headers carry the software version and year use the current
+	 * ones.
+	 *
+	 * The current values are the ones defined by index.php.
+	 *
+	 * Expected: each file matching VERSION_AND_YEAR_FILES matches
+	 *           getLicensePattern() with SMF_SOFTWARE_YEAR and SMF_VERSION from
+	 *           index.php.
 	 */
 	public function testFilesHaveCurrentVersionAndYear(): void
 	{

tests/Integration/GroupsTest.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2026 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 5-dev
+ */
+
 declare(strict_types=1);
 
 namespace SMF\Tests\Integration;
@@ -20,10 +31,17 @@ class GroupsTest extends IntegrationTestCase
 	 ****************/
 
 	/**
-	 * The query had no ORDER BY, so the database chose the order, and with a
-	 * limit it chose which members were listed at all. PostgreSQL returns a
-	 * row it has just rewritten after the others, which MySQL does not, so on
-	 * PostgreSQL the list changed as members' rows were updated.
+	 * Members of a membergroup are listed in the order they joined.
+	 *
+	 * Expected: listMembergroupMembers_Href($members, 1) lists two new
+	 *           administrators in id order, even after the earlier one's row has
+	 *           been rewritten.
+	 * Guards:   the query had no ORDER BY, so the database chose the order. A
+	 *           row that PostgreSQL has just rewritten is returned after the
+	 *           others, so there the list changed as members' rows were
+	 *           updated.
+	 *
+	 * @link https://github.com/SimpleMachines/SMF/pull/9721
 	 */
 	public function testMembersAreListedInTheOrderTheyJoined(): void
 	{
@@ -47,6 +65,14 @@ public function testMembersAreListedInTheOrderTheyJoined(): void
 
 	/**
 	 * With a limit, the members left out are the ones who joined last.
+	 *
+	 * Expected: listMembergroupMembers_Href($members, 1, $count - 1) returns true
+	 *           for "more" and lists every administrator but the last, in id
+	 *           order.
+	 * Guards:   with no ORDER BY and a limit, the database chose which members
+	 *           were listed at all.
+	 *
+	 * @link https://github.com/SimpleMachines/SMF/pull/9721
 	 */
 	public function testALimitKeepsTheMembersWhoJoinedFirst(): void
 	{

tests/Integration/HarnessTest.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2026 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 5-dev
+ */
+
 declare(strict_types=1);
 
 namespace SMF\Tests\Integration;
@@ -34,12 +45,22 @@ class HarnessTest extends IntegrationTestCase
 	 * Public methods
 	 ****************/
 
+	/**
+	 * The forum the suite runs against is installed, at the current version.
+	 *
+	 * Expected: modSettings['smfVersion'] is not empty and equals SMF_VERSION.
+	 */
 	public function testTheForumIsInstalled(): void
 	{
 		$this->assertNotEmpty(Config::$modSettings['smfVersion']);
 		$this->assertSame(SMF_VERSION, Config::$modSettings['smfVersion']);
 	}
 
+	/**
+	 * The configured database engine is one SMF supports.
+	 *
+	 * Expected: the lower-cased Config::$db_type is mysql or postgresql.
+	 */
 	public function testTheEngineIsOneSmfSupports(): void
 	{
 		$this->assertContains(
@@ -50,8 +71,14 @@ public function testTheEngineIsOneSmfSupports(): void
 	}
 
 	/**
-	 * Writes a row the next test then looks for. Together with the test below,
-	 * this is what proves the rollback in tearDown() is real.
+	 * A write is visible inside the test that made it.
+	 *
+	 * Writes a row the next test then looks for. Together with
+	 * testThatWriteIsGoneByTheNextTest(), this is what proves the rollback in
+	 * tearDown() is real.
+	 *
+	 * Expected: after replacing a setting, rawSetting() returns the value that
+	 *           was written.
 	 */
 	public function testAWriteIsVisibleInsideTheTestThatMadeIt(): void
 	{
@@ -66,6 +93,12 @@ public function testAWriteIsVisibleInsideTheTestThatMadeIt(): void
 		$this->assertSame('written', $this->rawSetting(self::LEFTOVER));
 	}
 
+	/**
+	 * The previous test's write is gone by the next test.
+	 *
+	 * Expected: rawSetting() for the variable the previous test wrote returns
+	 *           null.
+	 */
 	#[Depends('testAWriteIsVisibleInsideTheTestThatMadeIt')]
 	public function testThatWriteIsGoneByTheNextTest(): void
 	{
@@ -75,21 +108,41 @@ public function testThatWriteIsGoneByTheNextTest(): void
 		);
 	}
 
+	/**
+	 * Config::$modSettings is restored even though it is a static array.
+	 *
+	 * The rollback returns the table, not the copy in memory. tearDown() has to
+	 * put that back by hand, and testModSettingsHasNoLeftoversFromTheLastTest()
+	 * is the check that it does.
+	 *
+	 * Expected: a key written only to Config::$modSettings is present for the
+	 *           rest of this test.
+	 */
 	public function testModSettingsIsRestoredEvenThoughItIsAStaticArray(): void
 	{
-		// The rollback returns the table, not the copy in memory. tearDown() has
-		// to put that back by hand, and this is the check that it does.
 		Config::$modSettings['smf_tests_in_memory_only'] = 'x';
 
 		$this->assertArrayHasKey('smf_tests_in_memory_only', Config::$modSettings);
 	}
 
+	/**
+	 * Config::$modSettings has no leftovers from the last test.
+	 *
+	 * Expected: the key the previous test wrote only to memory is absent from
+	 *           Config::$modSettings.
+	 */
 	#[Depends('testModSettingsIsRestoredEvenThoughItIsAStaticArray')]
 	public function testModSettingsHasNoLeftoversFromTheLastTest(): void
 	{
 		$this->assertArrayNotHasKey('smf_tests_in_memory_only', Config::$modSettings);
 	}
 
+	/**
+	 * adminId() finds an administrator that actingAs() can become.
+	 *
+	 * Expected: adminId() returns a positive id, and after actingAs() with it
+	 *           User::$me->id is that id and User::$me->is_admin is true.
+	 */
 	public function testAdminIdFindsAnAdministrator(): void
 	{
 		$id = $this->adminId();
@@ -102,15 +155,25 @@ public function testAdminIdFindsAnAdministrator(): void
 		$this->assertTrue(\SMF\User::$me->is_admin, 'actingAs() did not produce an administrator');
 	}
 
+	/**
+	 * A test that does nothing logs no errors.
+	 *
+	 * Expected: assertNoErrorsLogged() passes in a test with an empty body.
+	 */
 	public function testNothingIsLoggedByAnEmptyTest(): void
 	{
 		$this->assertNoErrorsLogged();
 	}
 
 	/**
+	 * assertNoErrorsLogged() notices an error logged during the test.
+	 *
 	 * The assertion is only worth anything if it can fail, and it reads the log
 	 * through a watermark taken in setUp() rather than a count, so an empty log
 	 * is not what makes it pass.
+	 *
+	 * Expected: after a row is inserted into log_errors, assertNoErrorsLogged()
+	 *           throws AssertionFailedError.
 	 */
 	public function testAssertNoErrorsLoggedNoticesALoggedError(): void
 	{

tests/Integration/Http/CronTest.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2026 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 5-dev
+ */
+
 declare(strict_types=1);
 
 namespace SMF\Tests\Integration\Http;
@@ -40,13 +51,20 @@ class CronTest extends HttpTestCase
 	 ****************/
 
 	/**
-	 * cron.php can report an error, and carries on when it does.
+	 * An error in a task is logged by cron.php, and the task is cleared.
+	 *
+	 * Expected: requesting cron.php with a queued task whose class does not
+	 *           exist returns no fatal error, removes the task from
+	 *           background_tasks and logs a message naming the missing class.
+	 * Guards:   only Forum gave ErrorHandler its service, so anything cron.php
+	 *           tried to log threw a LogicException instead. TaskRunner's
+	 *           exception handler then tried to log that, and threw again. The
+	 *           request died with the task still claimed, so it ran again five
+	 *           minutes later: a notification email whose task logged so much
+	 *           as a warning was sent again every five minutes.
 	 *
-	 * Only Forum gave ErrorHandler its service, so anything cron.php tried to
-	 * log threw a LogicException instead. TaskRunner's exception handler then
-	 * tried to log that, and threw again. The request died with the task still
-	 * claimed, so it ran again five minutes later: a notification email whose
-	 * task logged so much as a warning was sent again every five minutes.
+	 * @link https://github.com/SimpleMachines/SMF/commit/058a81c27 Introduced by "wire the error handler service up to the new service implementation"
+	 * @link https://github.com/SimpleMachines/SMF/pull/9737
 	 */
 	public function testAnErrorInATaskIsLoggedAndTheTaskIsCleared(): void
 	{