From 62cbd87e71591bdd4c04f8cad07d6395d7f206c2 Mon Sep 17 00:00:00 2001
From: Harald Eilertsen <haraldei@anduin.net>
Date: Sat, 15 Jun 2024 13:00:19 +0200
Subject: Update API docs for Module test case base class.

---
 tests/unit/Module/TestCase.php | 104 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 98 insertions(+), 6 deletions(-)

(limited to 'tests')

diff --git a/tests/unit/Module/TestCase.php b/tests/unit/Module/TestCase.php
index 2959eab79..e92bc7083 100644
--- a/tests/unit/Module/TestCase.php
+++ b/tests/unit/Module/TestCase.php
@@ -1,8 +1,26 @@
 <?php
+/**
+ * This file contains the base class for module test cases.
+ *
+ * SPDX-FileCopyrightText: 2024 Hubzilla Community
+ * SPDX-FileContributor: Harald Eilertsen
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
 namespace Zotlabs\Tests\Unit\Module;
 
-class TestCase extends \Zotlabs\Tests\Unit\UnitTestCase {
+use Zotlabs\Tests\Unit\UnitTestCase;
+use App;
+
+/**
+ * Base class for writing module tests.
+ *
+ * This test class adds a number of helper methods to the base from
+ * the UnitTestCase class, useful when testing Modules (Controllers)
+ * that handle incoming requests.
+ */
+class TestCase extends UnitTestCase {
 
 	// Import PHPMock methods into this class
 	use \phpmock\phpunit\PHPMock;
@@ -12,7 +30,6 @@ class TestCase extends \Zotlabs\Tests\Unit\UnitTestCase {
 	 *
 	 * @param string $uri	The URI to request. Typically this will be the module
 	 *						name, followed by any req args separated by slashes.
-	 *
 	 * @param array $query	Assciative array of query args, with the parameters
 	 *						as keys.
 	 */
@@ -26,7 +43,9 @@ class TestCase extends \Zotlabs\Tests\Unit\UnitTestCase {
 		$_SERVER['REQUEST_METHOD'] = 'GET';
 		$_SERVER['SERVER_PROTOCOL'] = 'HTTP/1.1';
 		$_SERVER['QUERY_STRING'] = "q={$uri}";
+		// phpcs:disable Generic.PHP.DisallowRequestSuperglobal.Found
 		$_REQUEST = $_GET;
+		// phpcs::enable
 
 		\App::init();
 		\App::$page['content'] = '';
@@ -41,17 +60,44 @@ class TestCase extends \Zotlabs\Tests\Unit\UnitTestCase {
 	 * @param string $needle	The expected string to find.
 	 */
 	protected function assertPageContains(string $needle): void {
-		$this->assertStringContainsString($needle, \App::$page['content']);
+		$this->assertStringContainsString($needle, App::$page['content']);
 	}
 
 	/**
 	 * Stub out the `killme` function.
 	 *
-	 * Usefule for modules that call this function directly.
+	 * Useful for testing modules that call this function directly.
 	 *
 	 * Instead of calling exit, the stub will throw a `KillmeException`,
 	 * that can be caught by the test code to regain control after request
 	 * processing is terminated.
+	 *
+	 * **Example:**
+	 *
+	 *     public function test_something(): void {
+	 *         $this->stub_killme();
+	 *
+	 *         try {
+	 *             killme();
+	 *         } catch (KillmeException $e) {
+	 *             $this->assertSomething(...);
+	 *         }
+	 *     }
+	 *
+	 * It's also possible to use the builting PHPUnit expecations to verify
+	 * that the function was called.
+	 *
+	 *     public function test_something(): void {
+	 *         $this->stub_killme();
+	 *         $this->expectException(KillmeException::class);
+	 *
+	 *         killme();
+	 *     }
+	 *
+	 * This is useful if you only want to check that processing was terminated
+	 * with the `killme()` function.
+	 *
+	 * @throws KillmeException
 	 */
 	protected function stub_killme(): void {
 		$killme_stub = $this->getFunctionMock('Zotlabs\Module', 'killme');
@@ -64,6 +110,42 @@ class TestCase extends \Zotlabs\Tests\Unit\UnitTestCase {
 			);
 	}
 
+	/**
+	 * Stub out the `goaway` function.
+	 *
+	 * Useful for testing modules that calls this function directly.
+	 *
+	 * Instead of calling `killme()`, the stub will throw a RedirectException
+	 * with the target URL as the exception message. This allows the test code
+	 * to regain control after request processing is terminated.
+	 *
+	 * **Example:**
+	 *
+	 *     public function test_redirect(): void {
+	 *         $this->stub_goaway();
+	 *
+	 *         try {
+	 *             goaway('https://example.com/some_uri');
+	 *         } catch (RedirectException $e) {
+	 *             $this->assertEquals('https://example.com/some_uri', $e->getMessage());
+	 *             $this->assertSomethingElse(...);
+	 *         }
+	 *     }
+	 * It's also possible to use the builting PHPUnit expecations to verify
+	 * that the function was called.
+	 *
+	 *     public function test_something(): void {
+	 *         $this->stub_goaway();
+	 *         $this->expectException(RedirectException::class);
+	 *         $this->expectExceptionMessage('https://example.com/some_uri');
+	 *
+	 *         goaway('https://example.com/some_uri');
+	 *     }
+	 *
+	 * This is useful if you only want to check that the request was redirected.
+	 *
+	 * @throws RedirectException
+	 */
 	protected function stub_goaway(): void {
 		$goaway_stub = $this->getFunctionMock('Zotlabs\Module', 'goaway');
 		$goaway_stub
@@ -75,6 +157,16 @@ class TestCase extends \Zotlabs\Tests\Unit\UnitTestCase {
 			);
 	}
 
+	/**
+	 * Shorthand function to expect a redirect to a given URL.
+	 *
+	 * **Example:**
+	 *
+	 *     public function test_redirect(): void {
+	 *         $this->expectRedirectTo('https://example.com/some_uri');
+	 *         goaway('https://example.com/some_uri');
+	 *     }
+	 */
 	protected function expectRedirectTo(string $destination): void {
 		$this->stub_goaway();
 		$this->expectException(RedirectException::class);
@@ -90,8 +182,8 @@ class KillmeException extends \Exception {}
 /**
  * Exception class for goaway stub.
  *
- * Takes the goaway uri as an arg, and makes it available as
- * the public `$uri` member variable.
+ * Takes the goaway uri as an arg, and makes it available to the catch
+ * site via the `getMessage()` method.
  */
 class RedirectException extends \Exception {
 	function __construct(string $uri) {
-- 
cgit v1.2.3