aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHarald Eilertsen <haraldei@anduin.net>2024-06-15 13:00:19 +0200
committerHarald Eilertsen <haraldei@anduin.net>2024-06-16 08:57:09 +0200
commit62cbd87e71591bdd4c04f8cad07d6395d7f206c2 (patch)
tree4139ca13b05dcd8b74604666dde7719ccb94779a
parent72453c49f8d3467e6599f01cecbf8e5926b6bd65 (diff)
downloadvolse-hubzilla-62cbd87e71591bdd4c04f8cad07d6395d7f206c2.tar.gz
volse-hubzilla-62cbd87e71591bdd4c04f8cad07d6395d7f206c2.tar.bz2
volse-hubzilla-62cbd87e71591bdd4c04f8cad07d6395d7f206c2.zip
Update API docs for Module test case base class.
-rw-r--r--tests/unit/Module/TestCase.php104
1 files changed, 98 insertions, 6 deletions
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) {